From b77e51adf0f9d25ad1cee2af8c3407894d299fa6 Mon Sep 17 00:00:00 2001 From: Marko Date: Tue, 21 Mar 2023 13:11:56 +0100 Subject: [PATCH] docs: add adr/rfc section to contributing (#15385) Co-authored-by: Aaron Craelius Co-authored-by: Likhita Polavarapu <78951027+likhita-809@users.noreply.github.com> --- CONTRIBUTING.md | 9 +++++ docs/architecture/PROCESS.md | 18 +++++---- docs/rfc/PROCESS.md | 62 +++++++++++++++++++++++++++++++ docs/rfc/rfc-template.md | 72 ++++++++++++++++++++++++++++++------ 4 files changed, 141 insertions(+), 20 deletions(-) create mode 100644 docs/rfc/PROCESS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f52b1afc0c..b84bc6e302 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,7 @@ * [Pull Request Templates](#pull-request-templates) * [Requesting Reviews](#requesting-reviews) * [Updating Documentation](#updating-documentation) + * [RFC & ADR](#RFC & ADR) * [Dependencies](#dependencies) * [`go.work`](#gowork) * [`go.mod`](#gomod) @@ -163,6 +164,14 @@ If you open a PR on the Cosmos SDK, it is mandatory to update the relevant docum When writing documentation, follow the [Documentation Writing Guidelines](./docs/DOC_WRITING_GUIDELINES.md). +### RFC & ADR + +Within the Cosmos SDK we have two forms of documenting decisions, Request For Comment (RFC) & Architecture Design Record (ADR). They perform two different functions. The process for assessing if something needs an RFC is located in the respective folders: + +* [RFC Process](./docs/rfc/process.md) +* [ADR Process](./docs/adr/process.md) + + ## Dependencies We use [Go Modules](https://github.com/golang/go/wiki/Modules) to manage diff --git a/docs/architecture/PROCESS.md b/docs/architecture/PROCESS.md index c5140bbe41..ff83147316 100644 --- a/docs/architecture/PROCESS.md +++ b/docs/architecture/PROCESS.md @@ -6,21 +6,23 @@ 4. Add an entry to a list in the [README](./README.md) file. 5. Create a Pull Request to propose a new ADR. +## What is an ADR? + +An ADR is a document to document an implementation and design that may or may not have been discussed in an RFC. While an RFC is meant to replace synchoronus communication in a distributed environment, an ADR is meant to document an already made decision. An ADR wont come with much of a communication overhead because the discussion was recorded in an RFC or a synchronous discussion. If the consensus came from a synchoronus discussion then a short excerpt should be added to the ADR to explain the goals. + ## ADR life cycle -ADR creation is an **iterative** process. Instead of trying to solve all decisions in a single ADR pull request, we MUST firstly understand the problem and collect feedback through a GitHub Issue. +ADR creation is an **iterative** process. Instead of having a high amount of communication overhead, an ADR is used when there is already a decision made and implementation details need to be added. The ADR should document what the collective consensus for the specific issue is and how to solve it. -1. Every proposal SHOULD start with a new GitHub Issue or be a result of existing Issues. The Issue should contain just a brief proposal summary. +1. Every ADR should start with either an RFC or discussion where consensus has been met. -2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. +2. Once consensus is met, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`. -3. An ADR 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_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. -4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue. +4. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. -5. The PR SHOULD always be merged. In the case of a faulty ADR, we still prefer to merge it with a _rejected_ status. The only time the ADR SHOULD NOT be merged is if the author abandons it. - -6. Merged ADRs SHOULD NOT be pruned. +5. Merged ADRs SHOULD NOT be pruned. ### ADR status diff --git a/docs/rfc/PROCESS.md b/docs/rfc/PROCESS.md new file mode 100644 index 0000000000..a34af22694 --- /dev/null +++ b/docs/rfc/PROCESS.md @@ -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 an early feedback. +3. Make sure the context and a solution is clear and well documented. +4. Add an entry to a list in the [README](./README.md) file. +5. Create a Pull Request to propose a new ADR. + +## What is an RFC? + +An 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 Cosmos SDK team and contributors are distributed around the world. The team conducts working groups to have a synchronous discussion and an 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 Cosmos SDK is defining as a differentiation between RFC 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. An RFC is meant as a distributed colloboration session, it may have many comments and is usually the bi-product of no working group or synchornous communication + +1. Proposals could start with a new GitHub Issue, be a result of existing Issues or a discussion. + +2. An 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: An RFC is written when there is no working group or team session on the problem. RFC's are meant as a distributed white boarding session. If there is a working group on the proposal there is no need to have an RFC as there is synchornous 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 ADR-xxx + \ | + \ | + v v + ABANDONED +``` + +* `DRAFT`: [optional] an ADR which is work in progress, not being ready for a general review. This is to present an early work and get an early feedback in a Draft Pull Request form. +* `PROPOSED`: an ADR covering a full solution architecture and still in the review - project stakeholders haven't reached an agreed yet. +* `LAST CALL `: [optional] clear notify that we are close to accept updates. Changing a status to `LAST CALL` means that social consensus (of Cosmos SDK maintainers) has been reached and we still want to give it a time to let the community react or analyze. +* `ACCEPTED`: ADR which will represent a currently implemented or to be implemented architecture design. +* `REJECTED`: ADR can go from PROPOSED or ACCEPTED to rejected if the consensus among project stakeholders will decide so. +* `SUPERSEEDED by ADR-xxx`: ADR which has been superseded by a new ADR. +* `ABANDONED`: the ADR 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, personal form. diff --git a/docs/rfc/rfc-template.md b/docs/rfc/rfc-template.md index b3f4047751..417a795d08 100644 --- a/docs/rfc/rfc-template.md +++ b/docs/rfc/rfc-template.md @@ -2,21 +2,69 @@ ## Changelog -- {date}: {changelog} - -## Abstract - -> A brief high-level synopsis of the topic of discussion for this RFC, ideally -> just a few sentences. This should help the reader quickly decide whether the -> rest of the discussion is relevant to their interest. +* {date}: {changelog} ## Background -> Any context or orientation needed for a reader to understand and participate -> in the substance of the Discussion. If necessary, this section may include -> links to other documentation or sources rather than restating existing -> material, but should provide enough detail that the reader can tell what they -> need to read to be up-to-date. +> 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. + +## Descision + +> 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