Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

rfc: RFC process #96

Merged
merged 3 commits into from
Aug 19, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions rfc/0000-rfc-process.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
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)).
JP-Ellis marked this conversation as resolved.
Show resolved Hide resolved

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.
JP-Ellis marked this conversation as resolved.
Show resolved Hide resolved
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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we define who are the members that have decision/voting rights, or is that going over board?


1. Assign an RFC number based on the PR number, and update the filename and metadata.
2. Create a tracking issue in the Pact Foundation Roadmap repository for the implementation of the RFC. Where applicable, other issues may be created in other repositories.

## 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?
YOU54F marked this conversation as resolved.
Show resolved Hide resolved
- Does the proposed RFC process cover all the areas that it needs to, or are there any areas that are missing?
YOU54F marked this conversation as resolved.
Show resolved Hide resolved
- What should happen if an RFC is rejected? Is it sufficient to simply close the PR?
YOU54F marked this conversation as resolved.
Show resolved Hide resolved
59 changes: 59 additions & 0 deletions rfc/0000-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
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
---
<!--
The following is a template to help you write your RFC. You don't have to strictly follow this template, but it should help you to consider the various aspects of your proposal. If you have any questions, feel free to ask in the PR or in the Pact Slack community.
-->
## 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.