变更记录

  • {date}:{changelog}

背景

下一节是“背景”部分。该部分至少应包含两个段落,在某些情况下甚至可以占满整整一页。背景部分的指导目标是:作为一个刚接触该项目的人(新员工、团队转岗成员),我是否能够阅读背景部分并顺着其中的链接,获得关于为什么这项变更是
必要的完整上下文?
如果你不能把背景部分展示给一位随机工程师,并让他获得关于该 RFC 必要性的几乎完整上下文,那么背景部分就还不够充分。为帮助实现这一点,请在此按需链接到先前的 RFC、讨论以及其他相关材料,以提供上下文,这样你就不必只是重复已有内容。

提案

下一个必需部分是“提案”或“目标”。基于上述背景,本部分提出一个解决方案。 这里应概述解决方案“如何实现”,更详细的内容将在后续章节中说明。

已放弃的想法(可选)

随着 RFC 的演进,出现一些后来被放弃的想法是很常见的。与其直接将其从文档中删除,不如尝试将它们整理成若干部分,明确说明这些想法已被放弃,并解释放弃原因。 当你与他人分享 RFC,或未来有人回顾你的 RFC 时,大家很可能会走上同样的路径,并掉进那些我们后来已经成熟规避的陷阱。记录已放弃的想法,是为了识别这条路径,并解释其中的陷阱以及这些想法为何被放弃。

决策

本部分描述相对于所选设计的其他备选设计。本部分非常重要;如果一份 ADR 没有任何备选方案,那么应认为这份 ADR 缺乏充分思考。

影响(可选)

本部分描述应用该决策后的结果性上下文。所有影响都应列在这里,而不只是“正面”的影响。某项特定决策可能带来正面、负面和中性的影响,但它们都会在未来影响团队和项目。

向后兼容性

所有引入向后不兼容的 ADR 都必须包含一个章节,说明这些不兼容之处及其严重程度。ADR 必须解释作者打算如何处理这些不兼容问题。未对向后兼容性进行充分论述的 ADR 提交,可能会被直接拒绝。

正面

{positive consequences}

负面

{negative consequences}

中性

{neutral consequences}

参考资料

此处可添加为理解讨论所需的外部材料链接。 此外,如果意见征集中的讨论最终形成了任何设计决策,那么在讨论尘埃落定后,将相关 ADR 文档链接补充到这里也会很有帮助。

讨论

本部分包含讨论的核心内容。 本部分没有固定格式,但理想情况下,应在合并前更新本部分,以反映进行这些变更的 PR 中实际发生过的讨论。

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.