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

     1  - Feature Name:
     2  - Status: draft/in-progress/completed/rejected/obsolete/postponed
     3  - Start Date: YYYY-MM-DD
     4  - Authors:
     5  - RFC PR: (PR # after acceptance of initial draft)
     6  - Cockroach Issue: (one or more # from the issue tracker)
     7  
     8  **Remember, you can submit a PR with your RFC before the text is
     9  complete. Refer to the [README](README.md#rfc-process) for details.**
    10  
    11  # Summary
    12  
    13  One paragraph explanation of the proposed change.
    14  
    15  Suggested contents:
    16  - What is being proposed
    17  - Why (short reason)
    18  - How (short plan)
    19  - Impact
    20  
    21  # Motivation
    22  
    23  Why are we doing this? What use cases does it support? What is the expected outcome?
    24  
    25  # Guide-level explanation
    26  
    27  How do we teach this?
    28  
    29  Explain the proposal as if it was already included in the project and
    30  you were teaching it to another CockroachDB programmer. That generally means:
    31  
    32  - Introducing new named concepts.
    33  - Explaining the feature largely in terms of examples. Take into account that a product manager (PM) will want to connect back the work introduced by the RFC with user stories. Whenever practical, do ask PMs if they already have user stories that relate to the proposed work, and do approach PMs to attract user buy-in and mindshare if applicable.
    34  - Explaining how CockroachDB contributors and users should think about
    35    the feature, and how it should impact the way they use
    36    CockroachDB. It should explain the impact as concretely as possible.
    37  - If applicable, provide sample error messages, deprecation warnings, or migration guidance.
    38  - If applicable, describe the differences between teaching this to
    39    existing roachers and new roachers.
    40  
    41  For implementation-oriented RFCs (e.g. for core internals), this
    42  section should focus on how contributors should think about
    43  the change, and give examples of its concrete impact. For policy RFCs,
    44  this section should provide an example-driven introduction to the
    45  policy, and explain its impact in concrete terms.
    46  
    47  # Reference-level explanation
    48  
    49  This is the technical portion of the RFC. Explain the design in sufficient detail that:
    50  
    51  (You may replace the section title if the intent stays clear.)
    52  
    53  - Its interaction with other features is clear.
    54  - It covers where this feature may be surfaced in other areas of the product
    55     - If the change influences a user-facing interface, make sure to preserve consistent user experience (UX). Prefer to avoid UX changes altogether unless the RFC also argues for a clear UX benefit to users. If UX has to change, then prefer changes that match the UX for related features, to give a clear impression to users of homogeneous CLI / GUI elements. Avoid UX surprises at all costs. If in doubt, ask for input from other engineers with past UX design experience and from your design department.
    56  - It considers how to monitor the success and quality of the feature.
    57     - Your RFC must consider and propose a set of metrics to be collected, if applicable, and suggest which metrics would be useful to users and which need to be exposed in a public interface.
    58     - Your RFC should outline how you propose to investigate when users run into related issues in production. If you propose new data structures, suggest how they should be checked for consistency. If you propose new asynchronous subsystems, suggest how a user can observe their state via tracing. In general, think about how your coworkers and users will gain access to the internals of the change after it has happened to either gain understanding during execution or troubleshoot problems.
    59  - It is reasonably clear how the feature would be implemented.
    60  - Corner cases are dissected by example.
    61  
    62  The section should return to the examples given in the previous
    63  section, and explain more fully how the detailed proposal makes those
    64  examples work.
    65  
    66  ## Detailed design
    67  
    68  What / how.
    69  
    70  Outline both "how it works" and "what needs to be changed and in which order to get there."
    71  
    72  Describe the overview of the design, and then explain each part of the
    73  implementation in enough detail that reviewers will be able to
    74  identify any missing pieces. Make sure to call out interactions with
    75  other active RFCs.
    76  
    77  ## Drawbacks
    78  
    79  Why should we *not* do this?
    80  
    81  If applicable, list mitigating factors that may make each drawback acceptable.
    82  
    83  Investigate the consequences of the proposed change onto other areas of CockroachDB. If other features are impacted, especially UX, list this impact as a reason not to do the change. If possible, also investigate and suggest mitigating actions that would reduce the impact. You can for example consider additional validation testing, additional documentation or doc changes, new user research, etc.
    84  
    85  Also investigate the consequences of the proposed change on performance. Pay especially attention to the risk that introducing a possible performance improvement in one area can slow down another area in an unexpected way. Examine all the current "consumers" of the code path you are proposing to change and consider whether the performance of any of them may be negatively impacted by the proposed change. List all these consequences as possible drawbacks.
    86  
    87  ## Rationale and Alternatives
    88  
    89  This section is extremely important. See the
    90  [README](README.md#rfc-process) file for details.
    91  
    92  - Why is this design the best in the space of possible designs?
    93  - What other designs have been considered and what is the rationale for not choosing them?
    94  - What is the impact of not doing this?
    95  
    96  ## Unresolved questions
    97  
    98  - What parts of the design do you expect to resolve through the RFC
    99    process before this gets merged?
   100  - What parts of the design do you expect to resolve through the
   101    implementation of this feature before stabilization?
   102  - What related issues do you consider out of scope for this RFC that
   103    could be addressed in the future independently of the solution that
   104    comes out of this RFC?