Skip to content

Commit

Permalink
docs: add rfc section (#15354)
Browse files Browse the repository at this point in the history
  • Loading branch information
tac0turtle authored Mar 10, 2023
1 parent ee013c7 commit 16a5404
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 0 deletions.
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
---

# Requests for Comments

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}

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

0 comments on commit 16a5404

Please sign in to comment.