这期来聊聊写设计文档的实践。

起因是 @xxchan 在我们社区的 Sharing 频道分享了 @tison 之前写的旧文：如何参与 Apache 项目社区，并着重引用了这样一段话：

对于任何 non-trivial 的改动，都需要有一定的描述来表明动机；对于大的改动，更需要设计文档来留存记忆。人的记忆不是永久的，总会忘记最初的时候自己为什么做某一件事情，设计文档的沉淀对于社区摆脱人的不确定性演化有至关重要的作用。

我们社区的供应商中立存储库 go-storage 开发到现在积累了共 52 篇设计文档，在不断的探索如何写好，用好设计文档。

从历史上来看，go-storage 的设计文档演变大概经历了三个阶段：自娱自乐，自暴自弃，像模像样。

首先是自娱自乐的阶段。go-storage 最开始只是我的个人项目，设计文档更多的是写给自己看。在这个阶段，写设计文档更多的是为了理清自己的思路，避免过早的陷入到实现细节中去。但是从实际的经验来看，更多时候是实现的差不多了，写一篇文档来总结一下。比如说 go-storage 有记载的第一篇 proposal: Unify storager behavior。

然后是中间的自暴自弃阶段。在写了一段时间的 proposal 之后，由于始终没有什么反馈，写 proposal 的热情降到了谷底。开始觉得写 proposal 只是浪费时间，有这功夫不如直接把功能实现了。这也是 go-storage 最混乱的一段时间，引入了大量后来无法追溯的变更，一直到现在都在不断弥补那时候的旧帐。

最后也就是现在是像模像样的阶段。团队有了新的同学的加入，也产生了真正的基于 proposal 的讨论，完全的建立起一套基于 proposal 来讨论问题，推进实现的体系。整体流程大概是这样：

之前会采用一个独立的 specs repo 来维护这些 RFCs，在 GSP-139: Split Specs 之后，这些 RFCs 会拆分到各个项目内部，由对应项目的维护者来 review。