RFC 流程
一篇 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 的变更集包含:
- RFC 本身,两种语言,使用下一个空闲编号。
- 对状态文档的改动。RFC 在
affects里列出这些页面。这些页面各自在rfcs里列出这篇 RFC 的编号。
RFC 处于 draft 或 discussion 时,它新引入的状态页面的状态是 draft。
接受
满足下面几条时,RFC 可以被接受:
- 每个待决问题都已解决,或者写明理由后延期;
affects至少列出一个页面,并且这些页面已包含改动;- 检查通过。
接受时,两种语言里的状态都改为 accepted,这篇 RFC 新引入的页面也改为 accepted。
接受之后
已接受的 RFC 不再改写。只改它的状态、superseded_by 字段和明显的笔误。要改变一个决定,就写一篇新的 RFC,并在 supersedes 里写上旧的那篇。
状态文档和 RFC 不一致时,以状态文档为准。
编号
RFC 文件名是 NNNN-slug.md,四位数字。编号不复用,被否决和被撤回的 RFC 的编号也不复用。