本页内容
  1. RFC 包含什么
  2. 什么时候需要 RFC
  3. 生命周期
  4. 变更集
  5. 接受
  6. 接受之后
  7. 编号

一篇 RFC 记录一个技术决定:提议什么、为什么、否决了什么。本页规定什么时候需要 RFC,以及它如何从草稿走到被接受。

RFC 包含什么

RFC 写得薄。RFC 里放的是决定和理由,不放规范性条文。确切的规则、格式和行为写在 RFC 所改动的状态文档里:架构页、规范、手册页。这些改动和 RFC 属于同一个变更集。

想知道 cotty 做什么的读者,读状态文档。想知道为什么的读者,读 RFC。

骨架见模板。

什么时候需要 RFC

当一个决定符合下面任意一条时,写 RFC:

  • 难以撤销;
  • 跨越了别人依赖的边界:线上协议、磁盘格式、公开 API、安全模型;
  • 同时影响系统的多个部分;
  • 改变项目的运作方式。

修正错误、不改变含义的措辞澄清、不改变已有文档所述行为的组件内部细节,不需要 RFC。

产品上的改动不走 RFC,走版本设计。RFC 要写明它服务于哪个产品场景。

生命周期

状态 含义
draft 正在写。还不能做决定。
discussion 已写完,等待决定。
accepted 已决定。它影响的状态文档已更新。
implemented 代码与它一致。
rejected 决定不做。作为记录保留。
withdrawn 作者撤回。
superseded 被后来的 RFC 取代,后者写在 superseded_by 里。
stateDiagram-v2
    [*] --> draft
    draft --> discussion
    discussion --> draft
    discussion --> accepted
    discussion --> rejected
    draft --> withdrawn
    discussion --> withdrawn
    accepted --> implemented
    accepted --> superseded
    implemented --> superseded

是否接受由项目维护者决定。

变更集

一篇 RFC 的变更集包含:

  1. RFC 本身,两种语言,使用下一个空闲编号。
  2. 对状态文档的改动。RFC 在 affects 里列出这些页面。这些页面各自在 rfcs 里列出这篇 RFC 的编号。

RFC 处于 draft 或 discussion 时,它新引入的状态页面的状态是 draft。

接受

满足下面几条时,RFC 可以被接受:

  • 每个待决问题都已解决,或者写明理由后延期;
  • affects 至少列出一个页面,并且这些页面已包含改动;
  • 检查通过。

接受时,两种语言里的状态都改为 accepted,这篇 RFC 新引入的页面也改为 accepted。

接受之后

已接受的 RFC 不再改写。只改它的状态、superseded_by 字段和明显的笔误。要改变一个决定,就写一篇新的 RFC,并在 supersedes 里写上旧的那篇。

状态文档和 RFC 不一致时,以状态文档为准。

编号

RFC 文件名是 NNNN-slug.md,四位数字。编号不复用,被否决和被撤回的 RFC 的编号也不复用。