发布规范的项目如何管理文档
发布协议和提案的项目,是怎么让文档保持可用的?文档保持可读的那些项目,都维护一份现行规范,并把已接受的提案折叠进去。深度在现行文档里。提案要么很短,要么在接受后冻结。
发现
下面的说法除另有标注外都是 [官方]:是 2026-11-22 在项目自己的站点或仓库里读到的。
kitty
- 站点是一份用户手册(快速上手、概览、FAQ、更新日志等),外加一个叫 “Terminal protocol extensions” 的部分。这部分有 14 页。每页规定一个协议,读者是其他终端和程序的作者。
- 键盘协议那一页从现状的问题讲起。然后是快速上手、概览、渐进增强、支持探测和旧式编码。它列出了实现该协议的终端、库和程序。
- 要求用小写的 “must” 和 “should” 表述。页面上有一条 “Added in version 0.20.0” 的说明,没有修订历史。
- 站点用 Sphinx 和 Furo 主题构建。
- 看不到提案流程。这些页面似乎是直接修改的(未核实)。
pi,Earendil 出品
- pi-durable 这个包的文档分三层:
- 一份当作指南的 README:概念表、明确的规则,以及四十多个可运行的例子。
- 规范
docs/spec.md。它有 7303 行,开头是 “This document is normative”。第一章是术语和不变量,最后一章是非目标。 - 另外的设计文档。
packages/agent/docs/harness-v2.md是一篇 1655 行的设计文档。它是整篇重写的,提交说明里写了它取代之前的文档,以及改了什么。它的结构:- 开头是兼容性政策;
- 目标与非目标;
- 概念与不变量;
- 记录,以及标出可能崩溃位置的执行轨迹;
- 恢复;
- API 和实现;
- 待决问题、测试策略、实施顺序;
- 必读清单:一份"给全新的实现会话"的、按顺序排列的文件列表。
Earendil 的 RFC
- Earendil 在 rfc.earendil.com 发布 RFC,四位编号。它的 RFC 0001 定义了 draft、discussion、published、accepted 和 abandoned 这几个状态。被取代的 RFC 会写明取代它的是哪篇。
- 这些 RFC 很短。量了其中八篇,每篇约 300 到 1900 个英文词,没有共同的固定章节。
- 这个序列里除了技术决定,还有公司原则和调查。
MCP
- 提案叫 SEP。模板有摘要、动机、规范、理由、向后兼容、安全影响和参考实现。
- SEP 被接受时,同一个 pull request 必须补上规范正文、schema 改动和一条更新日志。要成为定稿,SEP 还需要参考实现,以及一个把每条要求对应到检查项的一致性测试。
- 定稿的 SEP 冻结不改。规范后来与它不一致时,以规范为准。
- 一个脚本把 SEP 文件渲染进文档,渲染结果过期时自动检查会失败。
- 站点托管在 Mintlify,这是一项商业服务。
ACP
- 提案叫 RFD。它们依次经过 Draft、Preview 和 Completed。只有 Completed 有稳定性承诺。
- 实验性的工作放在以 RFD 命名的功能开关后面。
- 站点托管在 Mintlify。
Matrix
- 提案叫 MSC。最终评议期之后,提案会停在一个叫 “spec PR missing” 的状态,直到改动被写进规范。这个改动必须链接到一个可用的实现。
- 在一个功能进入规范的正式版本之前,各实现使用不稳定前缀。
- 规范有正式版本,从 v1.1 到 v1.19,每个版本有更新日志。
凭一般了解
下面这些这次没有核实。
- Rust 维护 RFC,另外单独维护 Reference。
- TC39 的提案自带规范条文,并入 ECMA-262。
- IETF 只追加。TCP 的定义最后散在很多篇 RFC 里,于是写了 RFC 9293 来汇总。
对 cotty 的含义
- 维护现行文档,并把已接受的提案折叠进去。这就是文档体系里的折叠规则。
- 把深度放在规范和架构页里。规范页的标准是 kitty 的协议页。架构页的标准是 pi 的 harness 设计文档。
- RFC 写薄:只写决定和理由。
- 从别人那里拿三条做法:只有标为稳定的部分才有兼容性承诺;规范的效力高于提案;有代码之后,每条要求对应一个测试。
- 为实现者和 coding agent 而写。一份必读清单告诉新的会话从哪里开始。
来源
- kitty:文档、键盘协议
- pi:pi-durable README、harness-v2 提交
- Earendil:文章、RFC 归档
- MCP:SEP 指南
- ACP:RFD 流程
- Matrix:规范提案
没有覆盖
- Rust、TC39 和 IETF 的流程细节。
- Python PEP、Kubernetes KEP、Wayland 协议和 Tor 提案。