-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
8 changed files
with
203 additions
and
12 deletions.
There are no files selected for viewing
This file contains 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
This file contains 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
File renamed without changes.
File renamed without changes.
This file contains 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
This file contains 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,62 @@ | ||
| # RFC Creation Process | ||
|
|
||
| 1. Copy the `rfc-template.md` file. Use the following filename pattern: `rfc-next_number-title.md` | ||
| 2. Create a draft Pull Request if you want to get early feedback. | ||
| 3. Make sure the context and solution are clear and well-documented. | ||
| 4. Add an entry to the list in the [README](./README.md) file. | ||
| 5. Create a Pull Request to propose a new RFC. | ||
|
|
||
| ## What is a RFC? | ||
|
|
||
| A RFC is a sort of async whiteboarding session. It is meant to replace the need for a distributed team to come together to make a decision. Currently, the Noir team and contributors are distributed around the world. The team conducts working groups to have a synchronous discussion and a RFC can be used to capture the discussion for a wider audience to better understand the changes that are coming to the software. | ||
|
|
||
| The main difference the Noir is defining as a differentiation between RFCs and ADRs is that one is to come to consensus and circulate information about a potential change or feature. An ADR is used if there is already consensus on a feature or change and there is not a need to articulate the change coming to the software. An ADR will articulate the changes and have a lower amount of communication. | ||
|
|
||
| ## RFC life cycle | ||
|
|
||
| RFC creation is an **iterative** process. A RFC is meant as a distributed collaboration session, it may have many comments and is usually the by-product of no working group or synchronous communication. | ||
|
|
||
| 1. Proposals could start with a new GitHub Issue, be a result of existing Issues or a discussion. | ||
|
|
||
| 2. A RFC doesn't have to arrive to `main` with an _accepted_ status in a single PR. If the motivation is clear and the solution is sound, we SHOULD be able to merge it and keep a _proposed_ status. It's preferable to have an iterative approach rather than long, not merged Pull Requests. | ||
|
|
||
| 3. If a _proposed_ RFC is merged, then it should clearly document outstanding issues either in the RFC document notes or in a GitHub Issue. | ||
|
|
||
| 4. The PR SHOULD always be merged. In the case of a faulty RFC, we still prefer to merge it with a _rejected_ status. The only time the RFC SHOULD NOT be merged is if the author abandons it. | ||
|
|
||
| 5. Merged RFCs SHOULD NOT be pruned. | ||
|
|
||
| 6. If there is consensus and enough feedback then the RFC can be accepted. | ||
|
|
||
| > Note: A RFC is written when there is no working group or team session on the problem. RFCs are meant as a distributed whiteboarding session. If there is a working group on the proposal there is no need to have a RFC as there is synchronous whiteboarding going on. | ||
| ### RFC status | ||
|
|
||
| Status has two components: | ||
|
|
||
| ```text | ||
| {CONSENSUS STATUS} | ||
| ``` | ||
|
|
||
| #### Consensus Status | ||
|
|
||
| ```text | ||
| DRAFT -> PROPOSED -> LAST CALL yyyy-mm-dd -> ACCEPTED | REJECTED -> SUPERSEDED by RFC-xxx | ||
| \ | | ||
| \ | | ||
| v v | ||
| ABANDONED | ||
| ``` | ||
|
|
||
| * `DRAFT`: [optional] a RFC which is work in progress, not being ready for a general review. This is to present early work and get early feedback in a Draft Pull Request form. | ||
| * `PROPOSED`: a RFC covering a full solution architecture and still in review - project stakeholders haven't reached an agreement yet. | ||
| * `LAST CALL <date for the last call>`: [optional] clearly notify that we are close to accepting updates. Changing a status to `LAST CALL` means that social consensus (of Noir maintainers) has been reached and we still want to give it time to let the community react or analyze. | ||
| * `ACCEPTED`: RFC which will represent a currently implemented or to be implemented architecture design. | ||
| * `REJECTED`: RFC can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders decides so. | ||
| * `SUPERSEDED by RFC-xxx`: RFC which has been superseded by a new RFC. | ||
| * `ABANDONED`: the RFC is no longer pursued by the original authors. | ||
|
|
||
| ## Language used in RFC | ||
|
|
||
| * The background/goal should be written in the present tense. | ||
| * Avoid using a first-person form. |
This file contains 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,38 @@ | ||
| --- | ||
| sidebar_position: 1 | ||
| --- | ||
|
|
||
| # Requests for Comments | ||
|
|
||
| A Request for Comments (RFC) is a record of discussion on an open-ended topic | ||
| related to the design and implementation of the Noir, for which no | ||
| immediate decision is required. | ||
|
|
||
| The purpose of an RFC is to serve as a historical record of a high-level | ||
| discussion that might otherwise only be recorded in an ad-hoc way (for example, | ||
| via gists or Google docs) that are difficult to discover for someone after the | ||
| fact. An RFC _may_ give rise to more specific architectural _decisions_ for | ||
| the Noir, but those decisions must be recorded separately in | ||
| [Architecture Decision Records (ADR)](../architecture/README). | ||
|
|
||
| As a rule of thumb, if you can articulate a specific question that needs to be | ||
| answered, write an ADR. If you need to explore the topic and get input from | ||
| others to know what questions need to be answered, an RFC may be appropriate. | ||
|
|
||
| ## RFC Content | ||
|
|
||
| An RFC should provide: | ||
|
|
||
| * A **changelog**, documenting when and how the RFC has changed. | ||
| * An **abstract**, briefly summarizing the topic so the reader can quickly tell | ||
| whether it is relevant to their interest. | ||
| * Any **background** a reader will need to understand and participate in the | ||
| substance of the discussion (links to other documents are fine here). | ||
| * The **discussion**, the primary content of the document. | ||
|
|
||
| The [rfc-template.md](./rfc-template.md) file includes placeholders for these | ||
| sections. | ||
|
|
||
| ## Table of Contents | ||
|
|
||
|
|
This file contains 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,83 @@ | ||
| # RFC {RFC-NUMBER}: {TITLE} | ||
|
|
||
| ## Changelog | ||
|
|
||
| * {date}: {changelog} | ||
|
|
||
| ## Background | ||
|
|
||
| > The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole | ||
| > page in some cases. The guiding goal of the background section is: as a newcomer to this project (new employee, team | ||
| > transfer), can I read the background section and follow any links to get the full context of why this change is | ||
| > necessary? | ||
| > | ||
| > If you can't show a random engineer the background section and have them acquire nearly full context on the necessity | ||
| > for the RFC, then the background section is not full enough. To help achieve this, link to prior RFCs, discussions, and | ||
| > more here as necessary to provide context so you don't have to simply repeat yourself. | ||
|
|
||
| ## Proposal | ||
|
|
||
| > The next required section is "Proposal" or "Goal". Given the background above, this section proposes a solution. | ||
| > This should be an overview of the "how" for the solution, but for details further sections will be used. | ||
|
|
||
| ## Abandoned Ideas (Optional) | ||
|
|
||
| > As RFCs evolve, it is common that there are ideas that are abandoned. Rather than simply deleting them from the | ||
| > document, you should try to organize them into sections that make it clear they're abandoned while explaining why they | ||
| > were abandoned. | ||
| > | ||
| > When sharing your RFC with others or having someone look back on your RFC in the future, it is common to walk the same | ||
| > path and fall into the same pitfalls that we've since matured from. Abandoned ideas are a way to recognize that path | ||
| > and explain the pitfalls and why they were abandoned. | ||
| ## Decision | ||
|
|
||
| > This section describes alternative designs to the chosen design. This section | ||
| > is important and if an adr does not have any alternatives then it should be | ||
| > considered that the ADR was not thought through. | ||
| ## Consequences (optional) | ||
|
|
||
| > This section describes the resulting context, after applying the decision. All | ||
| > consequences should be listed here, not just the "positive" ones. A particular | ||
| > decision may have positive, negative, and neutral consequences, but all of them | ||
| > affect the team and project in the future. | ||
| ### Backwards Compatibility | ||
|
|
||
| > All ADRs that introduce backwards incompatibilities must include a section | ||
| > describing these incompatibilities and their severity. The ADR must explain | ||
| > how the author proposes to deal with these incompatibilities. ADR submissions | ||
| > without a sufficient backwards compatibility treatise may be rejected outright. | ||
| ### Positive | ||
|
|
||
| > {positive consequences} | ||
| ### Negative | ||
|
|
||
| > {negative consequences} | ||
| ### Neutral | ||
|
|
||
| > {neutral consequences} | ||
|
|
||
|
|
||
| ### References | ||
|
|
||
| > Links to external materials needed to follow the discussion may be added here. | ||
| > | ||
| > In addition, if the discussion in a request for comments leads to any design | ||
| > decisions, it may be helpful to add links to the ADR documents here after the | ||
| > discussion has settled. | ||
| ## Discussion | ||
|
|
||
| > This section contains the core of the discussion. | ||
| > | ||
| > There is no fixed format for this section, but ideally changes to this | ||
| > section should be updated before merging to reflect any discussion that took | ||
| > place on the PR that made those changes. |