docs: add adr/rfc section to contributing (#15385)
Co-authored-by: Aaron Craelius <aaron@regen.network> Co-authored-by: Likhita Polavarapu <78951027+likhita-809@users.noreply.github.com>
This commit is contained in:
Marko
GitHub
parent
5680f823c5
commit
b77e51adf0
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
62
docs/rfc/PROCESS.md
Normal file
62
docs/rfc/PROCESS.md
Normal file
@ -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 <date for the 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.
|
||||
@ -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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user