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.