diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..eda0f6c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: true +contact_links: + - name: ❓ Simple question - Slack chat + url: https://slack.pact.io + about: If you have a simple question, or want to discuss a feature request, join our Slack chat. + - name: ❓ Simple question - Stack Overflow + url: https://stackoverflow.com/questions/tagged/pact + about: The GitHub issue tracker is not for technical support. Please use Stack Overflow, and ask the community for help. diff --git a/.github/ISSUE_TEMPLATE/tracking-issue.yml b/.github/ISSUE_TEMPLATE/tracking-issue.yml new file mode 100644 index 0000000..79517e6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/tracking-issue.yml @@ -0,0 +1,56 @@ +name: 🏗️ Tracking Issue +description: A tracking issue to monitor the implementation of an approved RFC. +labels: [tracking] +body: + - type: markdown + attributes: + value: | + This is a tracking issue for an approved RFC. It is expected that the issue will be updated as the implementation progresses. + + Typically, the implementation will require changes across a number of other repositories within the Pact ecosystem. This issue should link to all of these related issues. + + GitHub can automatically monitor the implementation of related issues by using the following markdown: + + ```markdown + - [ ] pact-foundation/{repository}#{issue_number} + ``` + + - type: input + attributes: + label: RFC + description: The RFC number that this issue is tracking. + placeholder: "#123" + validations: + required: true + + - type: textarea + attributes: + label: Summary + description: | + The high-level summary of the feature being implemented. This should be copied from the approved RFC's summary. + validations: + required: true + + - type: textarea + attributes: + label: Implementation Plan + description: | + A plan of how the feature will be implemented. This may vary significantly for different RFCs, but should include a high-level overview of the changes required. + + This plan may be updated as the implementation progresses. + validations: + required: true + + - type: textarea + attributes: + label: Related Issues + description: | + A list of related issues that need to be implemented to complete this RFC. These issues should be linked to this tracking issue. + + GitHub can automatically monitor the implementation of related issues by using the following markdown: + + ```markdown + - [ ] pact-foundation/{repository}#{issue_number} + ``` + + You will need to create these issues in the relevant repositories. diff --git a/rfc/0000-rfc-process.md b/rfc/0000-rfc-process.md new file mode 100644 index 0000000..f82c96b --- /dev/null +++ b/rfc/0000-rfc-process.md @@ -0,0 +1,61 @@ +--- +name: rfc_process +started: 2024-07-04 +pr: pact-foundation/roadmap#0000 +--- +## Summary + +The Request for Comments (RFC) process is a way to propose and discuss changes to the Pact specification, ecosystem, and community. The RFC process ensures that changes are well-considered, documented, and communicated to all stakeholders. This RFC proposes the process itself, including how to submit an RFC, how to review and discuss it, and how to accept or reject it. + +## Motivation + +While the evolution of Pact and its ecosystem is open, the process for proposing and discussing changes is not well-defined. By introducing an RFC process, we can ensure that changes are well-considered, documented, and communicated to all stakeholders. This will help to ensure that changes are made in a transparent and collaborative way, and that the community has a voice in the direction of the Pact ecosystem. + +## Guide-level explanation + +### Scope of RFCs + +The Pact ecosystem is broad and includes, broadly speaking, the following areas: + +- The Pact specification itself ([pact-foundation/pact-specification](https://github.com/pact-foundation/pact-specification)) +- The Pact broker ([pact-foundation/pact-broker](pact-foundation/pact_broker)) +- The Pact CLI ([pact-foundation/pact-ruby-cli](https://github.com/pact-foundation/pact-ruby-cli)) +- The Pact FFI ([pact-foundation/pact-reference](https://github.com/pact-foundation/pact-reference/tree/master/rust/pact_ffi)). + +This RFC process is intended to cover any change which will impact the broader Pact ecosystem. + +While specific changes to the Pact implementation in various languages are generally out of scope[^1], we do wish to consider how changes in the areas above will impact the implementation in various languages. Furthermore, we may wish to introduce or formalize common conventions or guidelines that are applied across the various languages to ensure consistency, interoperability, and familiarity for users. + +[^1]: Changes to the Pact implementation in various languages are out of scope because they are managed by the maintainers of the individual language implementations (which may even have their own RFC process). + +### The Process + +The RFC process is intended to remain flexible while still ensuring that changes are well-considered, documented, and communicated to all stakeholders. The process is as follows: + +1. Fork the Pact Foundation Roadmap repository: [`https://github.com/pact-foundation/roadmap`](https://github.com/pact-foundation/roadmap) +2. Copy the `rfc/0000-template.md` file to `rfc/0000-my-feature.md`. Use a simple, descriptive name for the file, but do not assign an RFC number yet. +3. Fill in the RFC. +4. Submit a pull request. The pull request is where the RFC will be discussed, and reviewed. +5. Incorporate feedback, and iterate on the RFC. + +Eventually, a member of the Pact Foundation will either reject the RFC by closing the PR, or accept it by merging the PR. If the RFC is accepted, the following steps will also be taken: + +1. Creating a tracking issue in the Pact Foundation Roadmap repository for the implementation of the RFC. +2. Assign an RFC number based on the PR number, and update the filename and metadata (including link to the tracking issue to implementation). +3. Where applicable, other issues may be created in other repositories, with the tracking issue linking to these issues. + +## Drawbacks + +The RFC process may slow down the pace of change in the Pact ecosystem, since it introduces a formal process for proposing and discussing changes. This may be seen as a drawback by some, especially those who are used to a more informal process. + +## Rationale and alternatives + +The current process for changes has been ad-hoc and mostly informal. While this has allowed for rapid iteration and experimentation, it has made it difficult to track the reasoning behind changes as they are spread across various issues, pull requests, and (archived) Slack conversations. This has made it difficult for new contributors to understand the rationale behind changes, and for existing contributors to keep track of the changes. + +By introducing an RFC process, we can ensure that changes are well-considered, documented, and communicated to all stakeholders. This will help to ensure that changes are made in a transparent and collaborative way, and that the community has a voice in the direction of the Pact ecosystem. + +## Unresolved questions + +- Does the proposed RFC process balance ease with which changes can be proposed and discussed with the need for a formal process? +- Does the proposed RFC process cover all the areas that it needs to, or are there any areas that are missing? +- What should happen if an RFC is rejected? Is it sufficient to simply close the PR? diff --git a/rfc/0000-template.md b/rfc/0000-template.md new file mode 100644 index 0000000..52d6596 --- /dev/null +++ b/rfc/0000-template.md @@ -0,0 +1,60 @@ +--- +name: (fill me in with a unique ident, `my_awesome_feature`) +started: (fill me in with today's date, YYYY-MM-DD) +pr: pact-foundation/roadmap#0000 +tracking_issue: pact-foundation/roadmap#0000 +--- + +## Summary + +A one-paragraph explanation of the feature. + +## Motivation + +Why are we doing this? What use cases does it support? What is the expected outcome? + +## Guide-level explanation + +Explain the proposal as if it were already a part of Pact. That generally means: + +- Explaining the feature largely in terms of examples. +- Explaining how Pact users should *think* about the feature, and how it should impact the way they use Pact. It should explain the impact as concretely as possible. +- If applicable, provide sample error messages, deprecation warnings, or migration guidance. +- If applicable, describe the differences between teaching this to existing Pact users and new Pact users. +- Discuss how this impacts existing Pacts, and the Pact ecosystem in general. + +## Reference-level explanation + +This is the technical portion of the RFC. Explain the design in sufficient detail that: + +- Its interaction with other features is clear. +- It is reasonably clear how the feature would be implemented. +- Corner cases are dissected by example. + +The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work. + +## Drawbacks + +Why should we *not* do this? + +## Rationale and alternatives + +- Why is this design the best in the space of possible designs? +- What other designs have been considered and what is the rationale for not choosing them? +- What is the impact of not doing this? + +## Unresolved questions + +- What parts of the design do you expect to resolve through the RFC process before this gets merged? +- What parts of the design do you expect to resolve through the implementation of this feature before stabilization? +- What related issues do you consider out of scope for this RFC but could be addressed independently in future solutions? + +## Future possibilities + +Think about what the natural extension and evolution of your proposal would be and how it would affect the Pact specification, Pact users, and the ecosystem in a holistic way. This is also a good place to "dump ideas", if they are out of scope for the RFC you are writing but otherwise related. + +If you have tried and cannot think of any future possibilities, you may simply state that you cannot think of anything. + +Note that having something written down in the future-possibilities section is not a reason to accept the current or a future RFC; such notes should be in the section on motivation or rationale in this or subsequent RFCs. The section merely provides additional information.