RFC 最佳实践

本文档提供了有关作者和审核者如何充分利用 RFC 流程的指南。

将 RFC 视为设计文档

RFC 流程是 Fuchsia 项目做出决策的方式。某些 RFC 包含在整个项目中采用某些政策的决定。例如,RFC-0004 规定存储空间大小应采用 IEC 表示法(例如KiB,而不是 KB)。该 RFC 获得批准意味着,我们作为一个项目决定遵循该政策。不过,这些政策设置 RFC 相对较少。

大多数 RFC 本质上都是设计文档。设计文档 RFC 获得批准意味着,我们作为一个项目决定以某种方式解决问题。已接受的 RFC 是一种历史文档,记录了对该设计有利益的所有人都愿意继续推进该设计这一事实。

着重于争取认同

在编写 RFC(或任何其他内容)时,请问自己:“我为什么要编写这个?”

假设您编写 RFC 是因为您想要更改某些内容,但您认为所做的更改可能会影响项目的其他成员。在继续之前,请确保他们知道您打算做什么,并且不介意。这些可能受到您所做变更影响的人员就是您的利益相关方。当他们为您的 RFC 点赞并获得批准后,您将获得书面记录,证明他们对您的更改满意。请放心!

让此目标指导 RFC 的内容:

  • 强调需要利益相关方支持的设计方面。例如,利益相关方使用的接口比实现更重要。
  • 明确说明设计的影响。如果利益相关方需要费尽心思才能理解设计对他们的影响,审核速度就会很慢,并且在实现过程中,他们更有可能向您提出异议,说“这不是我同意的!”
  • 明确说明您要提议的内容。例如,RFC 可能包含有关设计如何运作的承诺,以及有关设计可能如何运作的说明性示例。它可以通过描述系统的现状以及实现完成后系统的未来状态来提供背景信息。让利益相关方能够轻松区分哪个是哪个。您不希望利益相关方看到您本意是提供要求的建议。

提供正确的详细信息

RFC 无需指定设计的每个细节。事实上,过多细节可能会使利益相关方更难理解设计的基本权衡。另一方面,如果您未提供足够的详细信息,不同的读者可能会对 RFC 的含义得出不同的结论。找到合适的详细程度是一门艺术。

RFC 应仅包含对设计可接受性有重大影响的所有详细信息。这些信息足以让利益相关方批准您的设计,并让日后阅读者了解设计获得批准的原因。附带的详细信息只会增加 RFC 的审核难度。

在审核过程中,有些 RFC 会变得越来越详细。这可能会让作者和利益相关方感到沮丧。当利益相关方就设计的某个部分提出问题(或对其提出异议)时,您的第一反应可能是添加更多详细信息来进行澄清或证明。在执行此操作之前,请考虑是否更适合移除详细信息。如果他们评论的部分对 RFC 没有实质性影响,您可以删除该部分或使其更笼统、更抽象,从而缩短讨论时间。

为了帮助您确定某个细节是否会对您的设计产生重大影响,请考虑以下问题:

  • 如果您更改了此详细信息,是否有人会因此将其投票从 +1 改为 -1?
  • 如果此详细信息的实现方式与所写内容不同,可以吗?您的利益相关方是否希望了解这项变更?
  • 您是否需要立即确定此详细信息?让实现者及其代码审核者做出决定是否更好?

考虑未来的读者

利益相关方是 RFC 的主要读者,但您不应忘记在 RFC 获得批准后,未来的读者也会尝试了解您的设计。以下是一些关于如何让更多人能够访问 RFC 的提示:

  • 假设您的利益相关方是首次通过 RFC 了解您的设计。提供足够的背景信息(或链接到包含相关信息的文档),以便将 RFC 置于背景中。
  • 假设利益相关方通过 RFC 了解您的设计。您和利益相关方可能会通过电子邮件、聊天、会议或至少代码审核评论来讨论 RFC。未来的读者无法轻松访问这些对话,因此请确保 RFC 文本包含您在非正式渠道得出的所有重要结论。
  • 使用稳定的链接。如果“背景信息”链接发生重大变化或变成 404 错误,RFC 将变得更难理解。请尽可能链接到文档的特定修订版,以便日后读者看到与您看到的相同页面。

请勿将 RFC 用作文档

获得批准后,RFC 会记录利益相关方对您设计的功能感到满意这一事实。不过,不应将其用作功能本身的文档。

RFC 和文档只是具有不同的目标:

  • 文档需要随着系统的变化不断更新,但 RFC 在被接受后不应更改(除小修订外)。
  • RFC 可向利益相关方证明设计为何合理且优于其他方案,但对用户可能没有太大帮助。
  • 文档提供了有关如何使用该功能的精确过程示例,但所需的详细程度对利益相关方而言并不实用。

请勿在代码或文档中链接到 RFC 来说明功能的运作方式。请为该功能提供自己的文档,并改为提供指向该文档的链接。

以下是关于放置此类文档的位置的一些建议:

  • 使用详细的文档注释添加有关特定 API 或代码模块的文档。
  • fuchsia.git 中创建 //src/my_subsystem/docs/ 子目录。 fuchsia.git 中托管的文档可以由 Gitiles 呈现,非常适合为子系统提供概念指南。
  • 如果您的文档对更广泛的 Fuchsia 社区有用,请将其添加到 fuchsia.dev

另一方面,RFC 可以链接到文档。事实上,如果您的 RFC 包含大量背景信息,不妨考虑将这些背景信息移至文档中,并在 RFC 中链接到这些信息!

更新这些最佳实践

如果您有关于最佳实践的建议(或认为上述某些最佳实践需要更新),请与 eng-council@fuchsia.dev 联系,或向 FEC 发送更改!