关于开源项目介绍:如何为开源项目撰写-RFC

对于 RFC

很多人都一再强调过 RFC 的重要性，@tison1 在 如何参加 Apache 我的项目社区2中提到：

对于任何 non-trivial 的改变，都须要有肯定的形容来表明动机；对于大的改变，更须要设计文档来留存记忆。人的记忆不是永恒的，总会遗记最后的时候本人为什么做某一件事件，设计文档的积淀对于社区解脱人的不确定性演变有至关重要的作用。

我在 如何在开源我的项目中做重构？3也具体论述了我对 RFC 的了解：

一个好的开源我的项目不仅仅是由代码组成，抛开开源共同体谈形象的技术和代码是没有意义的。因而向开源我的项目提交大型的变更之前，咱们必须要论述分明本人的想法，解释动机，让开源共同体晓得本人想做什么，想怎么做。

这些落到纸面上的文档在探讨时可能补充信息，欠缺想法，构建出更好的设计。从长期角度看，文档可能帮忙后来者了解过后为什么要提出这样的设计，从而防止反复踩坑。不仅如此，一份好的设计文档往往还可能影响、启发其余开源我的项目的设计，从而促成整个行业提高。

不难发现，运作良好的开源我的项目往往有着欠缺的 RFC 流程，他们之间的关系是相辅相成的：

•  Rust RFCs4
• CockroachDB RFCs5
• Ethereum EIPs6

那么问题来了：

如何撰写一份 RFC

在我看来撰写 RFC 是一件十分天然的事件，不晓得如何写的根本原因往往是筹备还不够。提出一个新的想法总是简略，然而将想法落地成为可行的计划须要付出艰辛的致力，RFC 就是这种致力的具象化。

我在撰写 RFC 的时候通常会经验如下步骤：

• 收集背景材料
• 剖析可行计划
• 撰写 RFC
• 社区探讨

收集背景材料

最辛苦也是最容易被脱漏的一步就是收集背景材料。

在有了一个好想法之后，咱们须要查阅历史的 RFC 和相干 Issues/PR 来理解这个这个想法是否可行。在这一步，咱们须要收集足够的材料以答复下列问题：

• 在此之前，相干的模块是如何工作？当初遇到了怎么的问题？是否确有必要做改变？
• 在相干畛域有没有相似的工作，现況如何？在其余我的项目中有没有相似的参考教训？
• 过来有没有思考过这个想法？当初为什么否决了它？当初状况产生了怎么的变动？

收集背景材料可能让咱们把握更多上下文，对相干模块理解更深刻，防止提出想当然的改良。其次，收集背景材料可能防止咱们进行反复的工作。毕竟太阳底下没有新鲜事，新想法可能早就曾经被前人尝试并论证过不可行。

在提出 RFC: Config Backward Compatibility 之前，我做了如下工作：

• 与提出相干问题的用户进行了一对一的沟通，理解了他的诉求和须要
• 浏览 Databend 与 Config 解决相干的外围逻辑，理解当初如何解决
• 理解其余相似我的项目如何实现 Config 兼容逻辑

剖析可行计划

在充沛把握背景材料后，下一步须要剖析可行的计划。

技术问题往往存在着多种可能性，不要尝试找到惟一的正确答案，而要在多种计划中做剖析和调研并挑选出绝对更好的计划。有时会须要开发出简略的 Demo 以验证本人的想法。

我在这一步中常常会犯下列的谬误：

• 偷懒：明晓得存在其余的可能性却不被动调研。这往往会导致进入探讨阶段时被社区指出并且十分被动地做追加解释，往返耗费的工夫远大于本人当时想思考分明。

• 门路依赖：设计方案时只思考应酬当下的问题，没有跳进去看到更好的可能。

• 自我辩护：诞生想法的同时往往也会附赠一个大略的思路，在调研的时候就很容易带有显著的偏差性，即便计划呈现了比较严重的问题也不违心放弃，而是一直减少扭曲的设定。

• 提前实现：在调研计划的时候就曾经写出了残缺的实现，最初计划的剖析变成了具体实现的探讨和复制。

这些问题往往会导致后续撰写 RFC 时呈现显著的偏差性，得出的论断有失偏颇。轻则 RFC 做大幅度调整，重则与维护者呈现重大的一致，甚至语言抵触。尽量避免相似的问题，努力做到公正主观的评估不同实现计划。当然，每个人都有本人的技术偏好，所以也不必过于奢求偏心，只有可能把劣势与弊病剖析分明即可。

撰写 RFC

在实现筹备工作之后才真正进入到撰写 RFC 的阶段。不同的我的项目往往有着不同的格局与要求，须要就地取材地做扭转。大部分 RFC 都会包含如下内容：

• 背景/动机
• 具体阐明
•  基本原理
• 未解决的问题
• 将来可能性

背景/动机 这个章节须要阐明本次变更的背景和动机，解释为什么要做这个变更，依据不同的状况，须要具体阐明也会略有不同。

比方新性能须要阐明为什么现有性能无奈满足需要，它将会反对怎么的应用场景，预期的产出是什么；性能重构批改则须要阐明现存的实现存在着哪些问题，之前做过什么尝试等。

具体阐明 这个章节则须要具体论述我的项目须要怎么做变更。同样须要依据我的项目理论状况做调整，以 Rust 为例，它将该章节分为两局部：

Guide-level explanation 解释从用户的角度看，这个变更带来了怎么的变动，引入了什么新概念，减少了什么新语法 Reference-level explanation 则从技术的角度阐明如何实现，与其余的个性如何交互，须要思考哪些边缘 case 留神在这个章节中不要大面积地粘贴具体的实现，而是扼要概要地阐明思路并辅以必要的代码，这将有助与 Reviewer 了解宏观思路而不是陷入到实现细节中。

基本原理 基本原理章节中须要解说为什么要这样来实现。

有没有其余的实现计划？他们各有什么优缺点，什么起因驱使咱们采纳了 A 计划而不是 B 计划？现存技术如何？其余我的项目是怎么实现的，他们各自思考的出发点如何？

未解决的问题 这个章节须要阐明本变更的局限性，比方在 review 中提出了某些目前还无奈解决的问题，能够将他们记录在该章节中。

将来可能性 将来可能性章节用于记录本变更将来的可能性，曾经思考到然而没有在本次变更中实现的想法。

比方引入了一个新个性，这个个性在将来可能与其余的个性做怎么样的联合。或者在 review 时有人提出超出以后 RFC 的范畴的想法，能够先记录在这里供前人参考。

社区探讨

在实现 RFC 后即可提交到社区进行探讨。

在经验这么多工作之后，咱们天然不心愿本人的 RFC 被否定，所以咱们须要踊跃地参加社区探讨，回应社区成员的关切，依据大家的反馈来调整本人的实现计划：补充没思考到的中央，调整实现的思路，必要的时候对 RFC 做拆分，实现其中的一部分等等。身处同一个开源共同体，社区成员的利益是趋势统一的，大家的终极目标都是为了把我的项目做好。将别人的拥护意见视作对本人想法的攻打，消极地与社区成员做反抗往往不利于 RFC 的进一步推动。

我为 Databend 提交的 RFC: Config Backward Compatibility7 已经是一个更大的 Scope：Versioned Config。在原始的 RFC 中，我打算为 databend config 引入 version 的概念，从而可能自信的做出破坏性变更。然而社区成员对该设计提出了复杂性的质疑，他们普遍认为这个设计太简单了，会引入十分多冗余的代码。不仅如此，Databend 目前还没有公布稳固版本，主观来看没有引入版本化配置的必要。联合社区的反馈意见，我做出了本人的回应8：

Our community members have great concern about the complexity of introducing a versioned config at this stage(no stable release, no production users). It seems better to only split outer and inner configs and leave the decision of versioned config till the future.

调整本次 RFC，将版本化配置的想法挪动到了 Future possibilities，本次变更只是引入一次重构，将裸露给用户的配置和外部应用的配置做拆分。在做出本次调整后，社区给出了 LGTM 并合并了这个 RFC，进入到具体的实现阶段。

总结

撰写 RFC 是跟社区沟通交流想法的无效渠道。通过实现收集背景材料、剖析可行计划、撰写 RFC和社区探讨等步骤，联合我的项目的理论，咱们谁都能够写出一份牢靠的提案。

给本人最爱的开源我的项目提交一份 Proposal 吧！

援用链接

[1] @tison: _https://github.com/tisonkun/_
[2] 如何参加 Apache 我的项目社区: _https://zhuanlan.zhihu.com/p/...
[3] 如何在开源我的项目中做重构？: _https://xuanwo.io/2022/01-ref...
[4] Rust RFCs: _https://github.com/rust-lang/...
[5] CockroachDB RFCs: _https://forum.cockroachlabs.c...
[6] Ethereum EIPs: _https://github.com/ethereum/E...
[7] RFC: Config Backward Compatibility: _https://github.com/datafusela...
[8] 回应: _https://github.com/datafusela...

对于 Databend

Databend 是一款开源、弹性、低成本，基于对象存储也能够做实时剖析的旧式数仓。期待您的关注，一起摸索云原生数仓解决方案，打造新一代开源 Data Cloud。

• Databend 文档：https://databend.rs
• Twitter：https://twitter.com/Datafuse_...
• Slack：https://datafusecloud.slack.com
• Wechat：Databend
• GitHub ：https://github.com/datafusela...

文章首发于公众号：Databend