2021-26: 设计文档的实践
source link: https://xuanwo.io/reports/2021-26/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
2021-26: 设计文档的实践
这期来聊聊写设计文档的实践。
起因是 @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 来讨论问题，推进实现的体系。整体流程大概是这样：
- 首先在 issues 或者论坛中提出一个大概的想法，比如 Feature gates are confusing
- 在得到一些反馈之后可以着手去写 RFC，我们称之为 GSP (go-storage proposal)：GSP-109: Redesign Features
- 我们学习 Golang & Rust 社区，使用 PR 的编号作为当前这个 proposal 的编号，能有效的避免冲突且方便找到对应的 PR
- 在 RFC 被 approve 之后，会创建一个 Tracking issue 来跟踪实现：Tracking issue for GSP-109: Redesign Features
之前会采用一个独立的 specs repo 来维护这些 RFCs，在 GSP-139: Split Specs 之后，这些 RFCs 会拆分到各个项目内部，由对应项目的维护者来 review。
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK