ADR 072: Re-instate a request-for-comments archive. (#6851)

This ADR restores a variation of the old Request for Comments documentation
that we previously used. The proposal differs from the original formulation,
and does not replace ADRs.

docs/architecture/README.md

@@ -98,3 +98,5 @@ Note the context/background should be written in the present tense.
 - [ADR-045: ABCI-Evidence](./adr-045-abci-evidence.md)
 - [ADR-057: RPC](./adr-057-RPC.md)
 - [ADR-069: Node Initialization](./adr-069-flexible-node-initialization.md)
+- [ADR-071: Proposer-Based Timestamps](adr-071-proposer-based-timestamps.md)
+- [ADR-072: Restore Requests for Comments](./adr-072-request-for-comments.md)

docs/architecture/adr-072-request-for-comments.md

@@ -0,0 +1,105 @@
+# ADR 72: Restore Requests for Comments
+
+## Changelog
+
+- 20-Aug-2021: Initial draft (@creachadair)
+
+## Status
+
+Proposed
+
+## Context
+
+In the past, we kept a collection of Request for Comments (RFC) documents in `docs/rfc`.
+Prior to the creation of the ADR process, these documents were used to document
+design and implementation decisions about Tendermint Core. The RFC directory
+was removed in favor of ADRs, in commit 3761aa69 (PR
+[\#6345](https://github.com/tendermint/tendermint/pull/6345)).
+
+For issues where an explicit design decision or implementation change is
+required, an ADR is generally preferable to an open-ended RFC: An ADR is
+relatively narrowly-focused, identifies a specific design or implementation
+question, and documents the consensus answer to that question.
+
+Some discussions are more open-ended, however, or don't require a specific
+decision to be made (yet). Such conversations are still valuable to document,
+and several members of the Tendermint team have been doing so by writing gists
+or Google docs to share them around. That works well enough in the moment, but
+gists do not support any kind of collaborative editing, and both gists and docs
+are hard to discover after the fact. Google docs have much better collaborative
+editing, but are worse for discoverability, especially when contributors span
+different Google accounts.
+
+Discoverability is important, because these kinds of open-ended discussions are
+useful to people who come later -- either as new team members or as outside
+contributors seeking to use and understand the thoughts behind our designs and
+the architectural decisions that arose from those discussion.
+
+With these in mind, I propose that:
+
+-  We re-create a new, initially empty `docs/rfc` directory in the repository,
+   and use it to capture these kinds of open-ended discussions in supplement to
+   ADRs.
+
+-  Unlike in the previous RFC scheme, documents in this new directory will
+   _not_ be used directly for decision-making. This is the key difference
+   between an RFC and an ADR.
+
+   Instead, an RFC will exist to document background, articulate general
+   principles, and serve as a historical record of discussion and motivation.
+
+   In this system, an RFC may _only_ result in a decision indirectly, via ADR
+   documents created in response to the RFC.
+
+   **In short:** If a decision is required, write an ADR; otherwise if a
+   sufficiently broad discussion is needed, write an RFC.
+
+Just so that there is a consistent format, I also propose that:
+
+-  RFC files are named `rfc-XXX-title.{md,rst,txt}` and are written in plain
+   text, Markdown, or ReStructured Text.
+
+-  Like an ADR, an RFC should include a high-level change log at the top of the
+   document, and sections for:
+
+     * Abstract: A brief, high-level synopsis of the topic.
+     * Background: Any background necessary to understand the topic.
+     * Discussion: Detailed discussion of the issue being considered.
+
+-  Unlike an ADR, an RFC does _not_ include sections for Decisions, Detailed
+   Design, or evaluation of proposed solutions. If an RFC leads to a proposal
+   for an actual architectural change, that must be recorded in an ADR in the
+   usual way, and may refer back to the RFC in its References section.
+
+## Alternative Approaches
+
+Leaving aside implementation details, the main alternative to this proposal is
+to leave things as they are now, with ADRs as the only log of record and other
+discussions being held informally in whatever medium is convenient at the time.
+
+## Decision
+
+(pending)
+
+## Detailed Design
+
+- Create a new `docs/rfc` directory in the `tendermint` repository. Note that
+  this proposal intentionally does _not_ pull back the previous contents of
+  that path from Git history, as those documents were appropriately merged into
+  the ADR process.
+
+- Create a `README.md` for RFCs that explains the rules and their relationship
+  to ADRs.
+
+- Create an `rfc-template.md` file for RFC files.
+
+## Consequences
+
+### Positive
+
+- We will have a more discoverable place to record open-ended discussions that
+  do not immediately result in a design change.
+
+### Negative
+
+- Potentially some people could be confused about the RFC/ADR distinction.

docs/rfc/README.md

@@ -0,0 +1,40 @@
+---
+order: 1
+parent:
+  order: false
+---
+
+# 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 Tendermint Core, 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
+Tendermint, 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) -->

docs/rfc/rfc-template.md

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