diff --git a/website/docs/implementation_guides/maintainer/checklist/readme.md b/website/docs/implementation_guides/maintainer/checklist/readme.md new file mode 100644 index 000000000..6730e9797 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/checklist/readme.md @@ -0,0 +1,21 @@ +--- +title: Checklist +sidebar_label: Checklist +--- + +# Checklist + +## Hygiene + +* [ ] Project created from template +* [ ] Documentation populated from template +* [ ] Documentation synced via automation to docs.pact.io +* [ ] Issue templates added +* [ ] Labels added +* [ ] Example projects created +* [ ] Tutorials/workshops to get started +* [ ] Supports minimum OS/Arch combinations? + +## Quality + +* [ ] TCK completed and published \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/consumer/readme.md b/website/docs/implementation_guides/maintainer/dsl/consumer/readme.md new file mode 100644 index 000000000..9975fd9cb --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/consumer/readme.md @@ -0,0 +1,10 @@ +--- +title: Consumer +sidebar_label: Consumer +--- + +# Consumer DSL + +- General consumer guidance +- Matching Rules +- Specification versions and how this impacts the DSL \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/http/readme.md b/website/docs/implementation_guides/maintainer/dsl/http/readme.md new file mode 100644 index 000000000..6246c8876 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/http/readme.md @@ -0,0 +1,13 @@ +--- +title: HTTP +sidebar_label: HTTP +--- + +# HTTP DSL + +## Consumer +TBC + +## Provider + +TBC \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/message/readme.md b/website/docs/implementation_guides/maintainer/dsl/message/readme.md new file mode 100644 index 000000000..a76a2f94e --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/message/readme.md @@ -0,0 +1,13 @@ +--- +title: Message +sidebar_label: Message +--- + +# Message DSL + +## Consumer +TBC + +## Provider + +TBC \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/plugins/readme.md b/website/docs/implementation_guides/maintainer/dsl/plugins/readme.md new file mode 100644 index 000000000..d155ea47a --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/plugins/readme.md @@ -0,0 +1,13 @@ +--- +title: Plugins +sidebar_label: Plugins +--- + +# Plugins DSL + +## Consumer +TBC + +## Provider + +TBC \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/provider/readme.md b/website/docs/implementation_guides/maintainer/dsl/provider/readme.md new file mode 100644 index 000000000..b16afead2 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/provider/readme.md @@ -0,0 +1,16 @@ +--- +title: Provider +sidebar_label: Provider +--- + +# Provider DSL + +- General provider guidance e.g. + - Pact fetching guidance (local, broker etc.) + - how to setup `pactffi_verifier_set_provider_info` and `pactffi_verifier_add_provider_transport` effectively to support multiple transports + - state handlers, request filters +- FFI calls +- Transports (multiple, how they work, default host/port) +- State Handlers (setup/teardown, use as hooks, and behaviour if there are no states) + + see https://pact-foundation.slack.com/archives/C02BXLDJ7JR/p1683037785422899 and https://pact-foundation.slack.com/archives/C02BXLDJ7JR/p1683282113939749 for more on this \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/dsl/readme.md b/website/docs/implementation_guides/maintainer/dsl/readme.md new file mode 100644 index 000000000..3b60146e8 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/dsl/readme.md @@ -0,0 +1,12 @@ +--- +title: DSL +sidebar_label: Introduction +--- + +# DSL + +DSL Implementation + +Covers Pact nomenclature vs idiomatic naming of things, how to cater for different spec versions, and FFI methods to call. + +*NOTE: It might make sense to split by consumer/provider, rather than use case* \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/example/readme.md b/website/docs/implementation_guides/maintainer/example/readme.md new file mode 100644 index 000000000..a412ef31f --- /dev/null +++ b/website/docs/implementation_guides/maintainer/example/readme.md @@ -0,0 +1,8 @@ +--- +title: Example +sidebar_label: Example +--- + +## Reference Example + +-> Annotated Pact JS/Pact Node code base \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/ffi/readme.md b/website/docs/implementation_guides/maintainer/ffi/readme.md new file mode 100644 index 000000000..811076b27 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/ffi/readme.md @@ -0,0 +1,15 @@ +--- +title: FFI +sidebar_label: FFI +--- + +## FFI (Framework? SDK?) + +- Introduction to the Pact Reference implementation / SDK framework / FFI +- Hello FFI (https://github.com/YOU54F/hello_ffi) +- Getting started (where to find, download) +- Ergonomics (make it easy on the end user) +- General usage, boundaries between FFI and Application +- Setting up for logging, debugging etc. +- Identifying the client language +- Specific methods to call (or should this be spread across the DSL implementation?) \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/general/readme.md b/website/docs/implementation_guides/maintainer/general/readme.md new file mode 100644 index 000000000..17ede63ff --- /dev/null +++ b/website/docs/implementation_guides/maintainer/general/readme.md @@ -0,0 +1,14 @@ +--- +title: General +sidebar_label: General +--- + +## General + +- Language / Naming Things / Idioms +- Minimum supported OS/Arch combinations +- Logging +- Debugging +- Repository hygiene (issue labels, triage etc.) +- Specification versions + - A short comparison between the different versions, and how this should be considered in API/DSL design \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/readme.md b/website/docs/implementation_guides/maintainer/readme.md new file mode 100644 index 000000000..ca74bbb2d --- /dev/null +++ b/website/docs/implementation_guides/maintainer/readme.md @@ -0,0 +1,16 @@ +--- +title: Introduction +sidebar_label: Introduction +--- + +## Introduction + +- Who it's for +- Ecosystem view: How it all hangs together (FFI, plugins, client language, CLI tools. Possibly use the diagrams from docs.pact.io/plugins) +- Maintainer meetings (how to stay in touch. Slack, Zoom monthly etc.) +- Roadmap (Where to find it, how to contribute to it, RFC process) +- Criteria for an implementation to be accepted into pact-foundation + - License should be MIT + - 2 maintainers (?) + - Agree to our community guidelines + - ...? \ No newline at end of file diff --git a/website/docs/implementation_guides/maintainer/testing/readme.md b/website/docs/implementation_guides/maintainer/testing/readme.md new file mode 100644 index 000000000..16e0774c7 --- /dev/null +++ b/website/docs/implementation_guides/maintainer/testing/readme.md @@ -0,0 +1,9 @@ +--- +title: Testing +sidebar_label: Testing +--- + +# Testing + +- Expectations for a quality Pact implementation +- Compatibility suite (should elements of this be threaded throughout the guide rather than its own section?) \ No newline at end of file diff --git a/website/sidebars.json b/website/sidebars.json index cbee9c7c1..708cf7b96 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -237,6 +237,26 @@ "wrapper_implementations" ] }, + { + "Maintainer Guide": [ + "implementation_guides/maintainer/readme", + "implementation_guides/maintainer/general/readme", + "implementation_guides/maintainer/ffi/readme", + { + "DSL": [ + "implementation_guides/maintainer/dsl/readme", + "implementation_guides/maintainer/dsl/consumer/readme", + "implementation_guides/maintainer/dsl/provider/readme", + "implementation_guides/maintainer/dsl/http/readme", + "implementation_guides/maintainer/dsl/message/readme", + "implementation_guides/maintainer/dsl/plugins/readme" + ] + }, + "implementation_guides/maintainer/testing/readme", + "implementation_guides/maintainer/checklist/readme", + "implementation_guides/maintainer/example/readme" + ] + }, { "Stubs": ["getting_started/stubs"] }, @@ -319,8 +339,7 @@ "recipes/lambdahttp", "recipes/cypress" ], - "Ecosystems": - ["diagrams/ecosystem"] + "Ecosystems": ["diagrams/ecosystem"] }, "pact_broker": { "Pact Broker": [ @@ -387,7 +406,11 @@ { "type": "category", "label": "API Docs", - "items": ["pact_broker/api/webhooks", "pact_broker/api/pacticipants", "pact_broker/api/pagination"] + "items": [ + "pact_broker/api/webhooks", + "pact_broker/api/pacticipants", + "pact_broker/api/pagination" + ] }, "pact_broker/changelog" ], @@ -415,7 +438,10 @@ "Events": [ "events", { - "Webinars and Workshops": ["events/plugins-framework-workshop", "events/plugins-framework-launch"] + "Webinars and Workshops": [ + "events/plugins-framework-workshop", + "events/plugins-framework-launch" + ] } ] },