github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/docs/RFCS/README.md (about)

     1  # About This Directory
     2  
     3  This directory contains RFCs (design documents) that describe proposed
     4  major changes to CockroachDB.
     5  
     6  # The Why of RFCs
     7  
     8  An RFC provides a high-level description of a major change or
     9  enhancement to Cockroach. The high-level description allows a reviewer
    10  to critique and poke holes in a design without getting lost in the
    11  particulars of code.
    12  
    13  An RFC is a form of communication aimed at both spreading and
    14  gathering knowledge, though it is not the sole means of accomplishing
    15  either task. Prototypes, tech notes, github issues, comments in code,
    16  commit messages and in-person discussions are valid alternatives
    17  depending on the situation.
    18  
    19  At its best, an RFC clearly and concisely describes the high-level
    20  architecture of a project giving confidence to all involved. At its
    21  worst, an RFC focuses on unimportant details, fosters discussion that
    22  stymies progress, or demoralizes the author with the complexity of
    23  their undertaking.
    24  
    25  # The When and How of RFCs
    26  
    27  When to write an RFC is nuanced and there are no firm rules. General
    28  guidance is to write an RFC before embarking on a significant or
    29  complex project that will be spread over multiple pull requests (PRs),
    30  and when multiple alternatives need to be considered and there is no
    31  obvious best approach. A project involving multiple people is a good
    32  signal an RFC is warranted. (Similarly, a project worthy of an RFC
    33  often requires multiple engineers worth of effort). Note that this
    34  guidance is intentionally vague. Many complex projects spread over
    35  multiple PRs do not require an RFC, though they do require adequate
    36  communication and discussion.<sup>[1](#sql-syntax)</sup>
    37  
    38  It is encouraged to develop a [prototype](PROTOTYPING.md) concurrently
    39  with writing the RFC. One of the significant benefits of an RFC is
    40  that it forces bigger picture thinking which reviewers can then
    41  disect. In contrast, a prototype forces the details to be considered,
    42  shedding light on the unknown unknowns and helping to ensure that the
    43  RFC focuses on the important design considerations.
    44  
    45  An RFC should be a high-level description which does not require
    46  formal correctness. There is utility in conciseness. Do not
    47  overspecify the details in the RFC as doing so can bury the reviewer
    48  in minutiae.<sup>[1](#sql-syntax)</sup> If you've never written an RFC
    49  before consider partnering with a more experienced engineer for
    50  guidance and to help shepherd your RFC through the process.
    51  
    52  # RFC Process
    53  
    54  1. Every RFC should have a dedicated reviewer familiar with the RFC's
    55     subject area.
    56  
    57  2. Copy `00000000_template.md` to a new file and fill in the
    58     details. Commit this version in your own fork of the repository or
    59     a branch.
    60  
    61  3. Submit a pull request (PR) to add your new file to the main
    62     repository. Each RFC should get its own pull request; do not
    63     combine RFCs with other files.
    64  
    65     Note: you can send a PR before the RFC is complete in order to
    66     solicit input about what to write in the RFC. In this case, include
    67     the term "[WIP]" (work in progress) in the PR title and use the
    68     label `do-not-merge`, until you are confident the RFC is complete
    69     and can be reviewed.
    70  
    71  4. Go through the PR review, iterating on the RFC to answer questions
    72     and concerns from the reviewer(s). The duration of this process
    73     should be related to the complexity of the project. If you or the
    74     reviewers seem to be at an impasse, consider in-person discussions
    75     or a prototype. There is no minimum time required to leave an RFC
    76     open for review. There is also no prohibition about halting or
    77     reversing work on an accepted RFC if a problem is discovered during
    78     implementation.
    79  
    80     Reviewers should be conscious of their own limitations and ask for
    81     other engineers to look at specific areas if necessary.
    82  
    83  5. Once discussion has settled and the RFC has received an LGTM from
    84     the reviewer(s):
    85  
    86     - change the `Status` field of the document to `in-progress`;
    87     - rename the RFC document to prefix it with the current date (`YYYYMMDD_`);
    88     - update the `RFC PR` field;
    89     - and merge the PR.
    90  
    91  6. Once the changes in the RFC have been implemented and merged,
    92     change the `Status` field of the document from `in-progress` to
    93     `completed`. If subsequent developments render an RFC obsolete,
    94     change its status to `obsolete`. When you mark a RFC as obsolete,
    95     ensure that its text references the other RFCs or PRs that make it
    96     obsolete.
    97  
    98  # Footnotes
    99  
   100  <a name="sql-syntax">1<a>: An exception to the general guidance on
   101  when an RFC is warranted is that anything more than trivial changes
   102  and extensions to SQL syntax require discussion within an
   103  RFC. Additionally, SQL syntax is a detail that an RFC should mention.