8f0d5b15f0
Co-authored-by: github-merge-queue <github-merge-queue@users.noreply.github.com> Co-authored-by: Julien Robert <julien@rbrt.fr> Co-authored-by: marbar3778 <marbar3778@yahoo.com>
84 lines
3.1 KiB
Markdown
84 lines
3.1 KiB
Markdown
# RFC {RFC-NUMBER}: {TITLE}
|
|
|
|
## Changelog
|
|
|
|
* {date}: {changelog}
|
|
|
|
## Background
|
|
|
|
> The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole
|
|
> page in some cases. The guiding goal of the background section is: as a newcomer to this project (new employee, team
|
|
> transfer), can I read the background section and follow any links to get the full context of why this change is
|
|
> necessary?
|
|
>
|
|
> If you can't show a random engineer the background section and have them acquire nearly full context on the necessity
|
|
> for the RFC, then the background section is not full enough. To help achieve this, link to prior RFCs, discussions, and
|
|
> more here as necessary to provide context so you don't have to simply repeat yourself.
|
|
|
|
|
|
## Proposal
|
|
|
|
> The next required section is "Proposal" or "Goal". Given the background above, this section proposes a solution.
|
|
> This should be an overview of the "how" for the solution, but for details further sections will be used.
|
|
|
|
|
|
## Abandoned Ideas (Optional)
|
|
|
|
> As RFCs evolve, it is common that there are ideas that are abandoned. Rather than simply deleting them from the
|
|
> document, you should try to organize them into sections that make it clear they're abandoned while explaining why they
|
|
> were abandoned.
|
|
>
|
|
> When sharing your RFC with others or having someone look back on your RFC in the future, it is common to walk the same
|
|
> path and fall into the same pitfalls that we've since matured from. Abandoned ideas are a way to recognize that path
|
|
> and explain the pitfalls and why they were abandoned.
|
|
|
|
## Decision
|
|
|
|
> This section describes alternative designs to the chosen design. This section
|
|
> is important and if an adr does not have any alternatives then it should be
|
|
> considered that the ADR was not thought through.
|
|
|
|
## Consequences (optional)
|
|
|
|
> This section describes the resulting context, after applying the decision. All
|
|
> consequences should be listed here, not just the "positive" ones. A particular
|
|
> decision may have positive, negative, and neutral consequences, but all of them
|
|
> affect the team and project in the future.
|
|
|
|
### Backwards Compatibility
|
|
|
|
> All ADRs that introduce backwards incompatibilities must include a section
|
|
> describing these incompatibilities and their severity. The ADR must explain
|
|
> how the author proposes to deal with these incompatibilities. ADR submissions
|
|
> without a sufficient backwards compatibility treatise may be rejected outright.
|
|
|
|
### Positive
|
|
|
|
> {positive consequences}
|
|
|
|
### Negative
|
|
|
|
> {negative consequences}
|
|
|
|
### Neutral
|
|
|
|
> {neutral consequences}
|
|
|
|
|
|
|
|
### 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.
|