-
Notifications
You must be signed in to change notification settings - Fork 3.6k
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
docs: add rfc section #15354
docs: add rfc section #15354
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
--- | ||
sidebar_position: 0 | ||
--- | ||
|
||
# Requests for Comments | ||
tac0turtle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
A Request for Comments (RFC) is a record of discussion on an open-ended topic | ||
related to the design and implementation of the Cosmos SDK, 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 Cosmos SDK, but those decisions must be recorded separately in | ||
[Architecture Decision Records (ADR)](../architecture/). | ||
|
||
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 | ||
|
||
<!-- - [RFC-NNN: Title](./rfc-NNN-title.md) --> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
{ | ||
"label": "RFCs", | ||
"position": 12, | ||
"link": null | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
# RFC {RFC-NUMBER}: {TITLE} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. we dont have this on the adr section, ideally we tell it to not show the template files like we do today There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah it is fine without it too. It was only required for the README to show properly I think. |
||
|
||
## 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. | ||
|
||
## 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 | ||
|
||
> 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My bad @tac0turtle , it was sidebar_position: 1 needed here.
As it is a main section, setting 0 makes it as important as the doc homepage readme :/