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>

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

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.
 
-## ADR life cycle
+## 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 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 life cycle
 
-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.
+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. 
 
-2. Once the motivation is validated, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`.
+1. Every ADR should start with either an RFC or discussion where consensus has been met. 
 
-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.
+2. Once consensus is met, a GitHub Pull Request (PR) is created with a new document based on the `adr-template.md`.
 
-4. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue.
+3. If a _proposed_ ADR is merged, then it should clearly document outstanding issues either in ADR document notes or in a GitHub Issue.
 
-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.
+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.
 
-6. Merged ADRs SHOULD NOT be pruned.
+5. Merged ADRs SHOULD NOT be pruned.
 
 ### ADR status
 

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 <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.

docs/rfc/rfc-template.md

@@ -2,21 +2,69 @@
 
 ## Changelog
 
-- {date}: {changelog}
+* {date}: {changelog}
 
-## Abstract
+## Background
 
-> 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.
+> 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}
 
-## 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.
 
 ### References