|
2 | 2 |
|
3 | 3 | ## Changelog |
4 | 4 |
|
5 | | -- {date}: {changelog} |
| 5 | +* {date}: {changelog} |
6 | 6 |
|
7 | | -## Abstract |
| 7 | +## Background |
8 | 8 |
|
9 | | -> A brief high-level synopsis of the topic of discussion for this RFC, ideally |
10 | | -> just a few sentences. This should help the reader quickly decide whether the |
11 | | -> rest of the discussion is relevant to their interest. |
| 9 | +> The next section is the "Background" section. This section should be at least two paragraphs and can take up to a whole |
| 10 | +> page in some cases. The guiding goal of the background section is: as a newcomer to this project (new employee, team |
| 11 | +> transfer), can I read the background section and follow any links to get the full context of why this change is |
| 12 | +> necessary? |
| 13 | +> |
| 14 | +> If you can't show a random engineer the background section and have them acquire nearly full context on the necessity |
| 15 | +> for the RFC, then the background section is not full enough. To help achieve this, link to prior RFCs, discussions, and |
| 16 | +> more here as necessary to provide context so you don't have to simply repeat yourself. |
| 17 | +
|
| 18 | + |
| 19 | +## Proposal |
| 20 | + |
| 21 | +> The next required section is "Proposal" or "Goal". Given the background above, this section proposes a solution. |
| 22 | +> This should be an overview of the "how" for the solution, but for details further sections will be used. |
| 23 | +
|
| 24 | + |
| 25 | +## Abandoned Ideas (Optional) |
| 26 | + |
| 27 | +> As RFCs evolve, it is common that there are ideas that are abandoned. Rather than simply deleting them from the |
| 28 | +> document, you should try to organize them into sections that make it clear they're abandoned while explaining why they |
| 29 | +> were abandoned. |
| 30 | +> |
| 31 | +> When sharing your RFC with others or having someone look back on your RFC in the future, it is common to walk the same |
| 32 | +> path and fall into the same pitfalls that we've since matured from. Abandoned ideas are a way to recognize that path |
| 33 | +> and explain the pitfalls and why they were abandoned. |
| 34 | +
|
| 35 | +## Descision |
| 36 | + |
| 37 | +> This section describes alternative designs to the chosen design. This section |
| 38 | +> is important and if an adr does not have any alternatives then it should be |
| 39 | +> considered that the ADR was not thought through. |
| 40 | +
|
| 41 | +## Consequences (optional) |
| 42 | + |
| 43 | +> This section describes the resulting context, after applying the decision. All |
| 44 | +> consequences should be listed here, not just the "positive" ones. A particular |
| 45 | +> decision may have positive, negative, and neutral consequences, but all of them |
| 46 | +> affect the team and project in the future. |
| 47 | +
|
| 48 | +### Backwards Compatibility |
| 49 | + |
| 50 | +> All ADRs that introduce backwards incompatibilities must include a section |
| 51 | +> describing these incompatibilities and their severity. The ADR must explain |
| 52 | +> how the author proposes to deal with these incompatibilities. ADR submissions |
| 53 | +> without a sufficient backwards compatibility treatise may be rejected outright. |
| 54 | +
|
| 55 | +### Positive |
| 56 | + |
| 57 | +> {positive consequences} |
| 58 | +
|
| 59 | +### Negative |
| 60 | + |
| 61 | +> {negative consequences} |
| 62 | +
|
| 63 | +### Neutral |
| 64 | + |
| 65 | +> {neutral consequences} |
12 | 66 |
|
13 | | -## Background |
14 | 67 |
|
15 | | -> Any context or orientation needed for a reader to understand and participate |
16 | | -> in the substance of the Discussion. If necessary, this section may include |
17 | | -> links to other documentation or sources rather than restating existing |
18 | | -> material, but should provide enough detail that the reader can tell what they |
19 | | -> need to read to be up-to-date. |
20 | 68 |
|
21 | 69 | ### References |
22 | 70 |
|
|
0 commit comments