github.com/ari-anchor/sei-tendermint@v0.0.0-20230519144642-dc826b7b56bb/docs/architecture/adr-072-request-for-comments.md (about)

     1  # ADR 72: Restore Requests for Comments
     2  
     3  ## Changelog
     4  
     5  - 20-Aug-2021: Initial draft (@creachadair)
     6  
     7  ## Status
     8  
     9  Implemented
    10  
    11  ## Context
    12  
    13  In the past, we kept a collection of Request for Comments (RFC) documents in `docs/rfc`.
    14  Prior to the creation of the ADR process, these documents were used to document
    15  design and implementation decisions about Tendermint Core. The RFC directory
    16  was removed in favor of ADRs, in commit 3761aa69 (PR
    17  [\#6345](https://github.com/tendermint/tendermint/pull/6345)).
    18  
    19  For issues where an explicit design decision or implementation change is
    20  required, an ADR is generally preferable to an open-ended RFC: An ADR is
    21  relatively narrowly-focused, identifies a specific design or implementation
    22  question, and documents the consensus answer to that question.
    23  
    24  Some discussions are more open-ended, however, or don't require a specific
    25  decision to be made (yet). Such conversations are still valuable to document,
    26  and several members of the Tendermint team have been doing so by writing gists
    27  or Google docs to share them around. That works well enough in the moment, but
    28  gists do not support any kind of collaborative editing, and both gists and docs
    29  are hard to discover after the fact. Google docs have much better collaborative
    30  editing, but are worse for discoverability, especially when contributors span
    31  different Google accounts.
    32  
    33  Discoverability is important, because these kinds of open-ended discussions are
    34  useful to people who come later -- either as new team members or as outside
    35  contributors seeking to use and understand the thoughts behind our designs and
    36  the architectural decisions that arose from those discussion.
    37  
    38  With these in mind, I propose that:
    39  
    40  -  We re-create a new, initially empty `docs/rfc` directory in the repository,
    41     and use it to capture these kinds of open-ended discussions in supplement to
    42     ADRs.
    43  
    44  -  Unlike in the previous RFC scheme, documents in this new directory will
    45     _not_ be used directly for decision-making. This is the key difference
    46     between an RFC and an ADR.
    47  
    48     Instead, an RFC will exist to document background, articulate general
    49     principles, and serve as a historical record of discussion and motivation.
    50  
    51     In this system, an RFC may _only_ result in a decision indirectly, via ADR
    52     documents created in response to the RFC.
    53  
    54     **In short:** If a decision is required, write an ADR; otherwise if a
    55     sufficiently broad discussion is needed, write an RFC.
    56  
    57  Just so that there is a consistent format, I also propose that:
    58  
    59  -  RFC files are named `rfc-XXX-title.{md,rst,txt}` and are written in plain
    60     text, Markdown, or ReStructured Text.
    61  
    62  -  Like an ADR, an RFC should include a high-level change log at the top of the
    63     document, and sections for:
    64  
    65       * Abstract: A brief, high-level synopsis of the topic.
    66       * Background: Any background necessary to understand the topic.
    67       * Discussion: Detailed discussion of the issue being considered.
    68  
    69  -  Unlike an ADR, an RFC does _not_ include sections for Decisions, Detailed
    70     Design, or evaluation of proposed solutions. If an RFC leads to a proposal
    71     for an actual architectural change, that must be recorded in an ADR in the
    72     usual way, and may refer back to the RFC in its References section.
    73  
    74  ## Alternative Approaches
    75  
    76  Leaving aside implementation details, the main alternative to this proposal is
    77  to leave things as they are now, with ADRs as the only log of record and other
    78  discussions being held informally in whatever medium is convenient at the time.
    79  
    80  ## Decision
    81  
    82  (pending)
    83  
    84  ## Detailed Design
    85  
    86  - Create a new `docs/rfc` directory in the `tendermint` repository. Note that
    87    this proposal intentionally does _not_ pull back the previous contents of
    88    that path from Git history, as those documents were appropriately merged into
    89    the ADR process.
    90  
    91  - Create a `README.md` for RFCs that explains the rules and their relationship
    92    to ADRs.
    93  
    94  - Create an `rfc-template.md` file for RFC files.
    95  
    96  ## Consequences
    97  
    98  ### Positive
    99  
   100  - We will have a more discoverable place to record open-ended discussions that
   101    do not immediately result in a design change.
   102  
   103  ### Negative
   104  
   105  - Potentially some people could be confused about the RFC/ADR distinction.