wip: example ToC for maintainer guide #270
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| --- | ||
| title: Consumer | ||
| sidebar_label: Consumer | ||
| --- | ||
|
|
||
| # Consumer DSL | ||
|
|
||
| - General consumer guidance | ||
| - Matching Rules | ||
| - Specification versions and how this impacts the DSL |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| title: HTTP | ||
| sidebar_label: HTTP | ||
| --- | ||
|
|
||
| # HTTP DSL | ||
|
|
||
| ## Consumer | ||
| TBC | ||
|
|
||
| ## Provider | ||
|
|
||
| TBC |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| title: Message | ||
| sidebar_label: Message | ||
| --- | ||
|
|
||
| # Message DSL | ||
|
|
||
| ## Consumer | ||
| TBC | ||
|
|
||
| ## Provider | ||
|
|
||
| TBC |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| title: Plugins | ||
| sidebar_label: Plugins | ||
| --- | ||
|
|
||
| # Plugins DSL | ||
|
|
||
| ## Consumer | ||
| TBC | ||
|
|
||
| ## Provider | ||
|
|
||
| TBC |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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* |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| title: Example | ||
| sidebar_label: Example | ||
| --- | ||
|
|
||
| ## Reference Example | ||
|
|
||
| -> Annotated Pact JS/Pact Node code base |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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?) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
|
Member
There was a problem hiding this comment. yeah we have a handful of Apache 2.0 repos. I noted about 9 don't have licenses, which probably should so will flag them for review. |
||
| - 2 maintainers (?) | ||
| - Agree to our community guidelines | ||
| - ...? | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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?) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just a thought for checklist, from previous threads
sustainable CI, or repo pre-reqs, good practises.
pact-foundation/roadmap#8
in addition, docs, ie
etc
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, nice ideas. I just popped a few off the top of my head, but I think it will likely be getting down what we have initially with some "TODOs" that we can populate over time as needed.