Skip to content
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

Merged
merged 2 commits into from
Mar 10, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions docs/rfc/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
sidebar_position: 0
Copy link
Member

@julienrbrt julienrbrt Mar 10, 2023

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.
image
As it is a main section, setting 0 makes it as important as the doc homepage readme :/

---

# 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) -->
5 changes: 5 additions & 0 deletions docs/rfc/_category.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"label": "RFCs",
"position": 12,
"link": null
}
35 changes: 35 additions & 0 deletions docs/rfc/rfc-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# RFC {RFC-NUMBER}: {TITLE}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

---
sidebar_position: 1
---

?

Copy link
Member Author

Choose a reason for hiding this comment

The 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

Copy link
Member

Choose a reason for hiding this comment

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