这里应该包含一个关于你的项目使命的简短描述(3-5句话)。其目的是说明项目打算做什么,并帮助外部的贡献者大致了解项目的哪些类型的功能可能会受到欢迎。
参见《生产开源软件》中的使命宣言篇。
这一部分应该包含为第一次使用的用户编写的关于如何开始使用这个项目的简短文档。其它的详细信息文档可以通过链接的方式加入这个小节。
这一部分可以列出以下任何或全部内容。
软件所涉及的功能、用例的清单。
用于解决权衡问题的设计原则的信息
用户级文档的链接
常见问题(FAQ)的答案,最好是可以链接到具体问题及其答案的格式,以方便参考。
这一部分应该包含一个简短的文档,让用户了解如何获得项目的帮助。 文档可以很简单,如果你的项目想要回答问题的话,可以把用户指向问题追踪链接。 它也可以指向一个存档和可搜索的聊天频道,或者存档的可搜索邮件列表,或者在线用户论坛。
这一部分应该包括如何与该项目取得联系的信息。通常,这将包含存档的、可搜索的和可链接的沟通渠道的链接。
这是一个给项目的 Trusted Committer 以荣誉的好地方。
这里可以包括作为一个 Trusted Committer 人对这个项目意味着什么的信息--尽管理想情况下, 一个组织中的所有项目都使用相同的定义,而这里提供的只是指向这个定义的链接。在这里保留链接的原因是为了让那些没有或很少 在内源项目中工作和贡献经验的同事能够直接从他们日常工作中需要的技术项目链接中获取到公司范围内的信息。
这一部分应该记录(或链接到文档)所有第一次贡献者需要知道的事情,以便更好开展工作。通常情况下,文档中不会包含下面的所有主题。 文档描述的重点是你的项目中与标准设置不同的地方,以及以前的贡献者认为难以理解的地方。
如何获取源代码。
如何找到你的项目需要帮助的问题清单--这些问题既可以是技术性的,也可以是非技术性的。一般来说,你会把这些问题放在问题跟踪器中,供贡献者访问。
链接到更多的文件,例如关于项目的结构、一般的编码风格、测试惯例......。
对于技术贡献。进行代码修改,构建项目并测试你的修改。
将你的修改提交给项目。
理想情况下,你还应该包括关于项目的首选开发流程的信息。贡献者应该先打开一个issue并提交修改提案,还是欢迎他们立即提交修改? 在检视贡献时,什么对你来说是重要的?
此外,你应该概述你希望在项目中遵循的任何设计原则。将这些原则明确化往往有助于更快、更容易地解决权衡问题解决方案。 此外,它还有助于使原本隐含的假设变得透明。
随着时间的推移,你会注意到这一节会有很大的增长。在这种情况下,可以考虑将这些信息转移到不同的文件中,例如,CONTRIBUTING.md
和TESTING.md
。
功能名称。(请填写一个独特的身份,my_awesome_feature
)
开始日期: (填写今天的日期,YYY-MM-DD)
被提名的负责人:(受RFC影响的技术领域专家代表。这通常是技术负责人,但他们可以委托。在所有被提名的所有者签字之前,RFC不能被接受。)
一段对该功能的解释。
这一部分对于让我们从正在实施的事情中学习是至关重要的。
什么时候进行回顾?
[] 复盘完成?
(将在哪里/如何举行,人们如何参与,结果在哪里?)
我们为什么要这样做?它支持什么用例?预期的结果是什么?
就像在向另一个工程师介绍一个已经存在的提案一样介绍该提案。这通常意味着:
引入新的命名概念。
用示例来解释主要特点。
解释工程师是如何思考这个功能的。应该尽可能具体地解释其带来的影响。
如果适用的话(例如代码/架构建议),提供错误信息样本、弃用警告信息或迁移指导文档。
如果适用的话,描述向现有的工程师和新的工程师传授这些知识的区别。
对于面向实现的RFC来说,这一部分应该关注贡献者应该如何思考这个变化,并举例说明其具体影响。对于政策/流程型RFC,本节应提供一个以实例为导向的政策/流程介绍,并具体解释其影响。
这是RFC的技术部分。对设计进行足够详细的介绍,以便
它与其他功能的交互是清晰的。
合理地清楚介绍该功能将如何实现。
通过实例剖析如何处理极端情况。
该部分应该回到上一节给出的例子,并更充分地详细地解释如何实现这些例子的。
为什么我们不应该这样做?
为什么这个设计是可能的设计空间中最好的?
还有哪些设计被考虑过,不选择这些设计的理由是什么?
不这样做的影响是什么?
讨论与本提案有关的现有技术,包括好的和坏的。 这可以包括几个例子。
对于语言、库、工具等。这个功能在其他地方是否存在,他们的社区有什么经验?
对于社区建议。这个功能是否由在其他社区已经实现了,他们在这方面有什么经验?
对于其他团队。我们可以从其他社区所做的事情中吸取什么教训?
论文。是否有任何已发表的论文或有相关的帖子来讨论这个问题?如果你有一些相关的论文可以参考,这可以作为一个更详细的理论背景。
这一部分的目的是鼓励你作为作者思考其他地方的经验教训,为你的RFC的读者提供更全面的信息。 如果没有现有技术,那也没关系--你的想法无论是否是全新的,还是从其他地方改编而来,我们都很感兴趣。
在提案被接受之前,你希望通过RFC过程来解决哪些部分的设计问题?
在提案酝酿成熟之前,你希望通过实现这个功能来解决哪些部分的设计问题?
你认为哪些相关问题超出了本RFC的范围,可以在未来独立于本RFC的解决方案而得到解决?
思考你的提案的自然延伸和演变是什么,以及它将如何全面地影响团队和项目。 试着把这一节作为一个工具,更全面地考虑你的提案中与项目和团队的所有可能的相互作用。 还要考虑这一切如何与项目和相关子团队的路线图相适应。 这也是一个 "倾倒想法 "的好地方,如果它们超出了你正在写的RFC的范围,但又与之相关。 如果这些想法超出了你正在写的RFC的范围,但又与之相关,那么这里也是 "抛弃想法 "的好地方。 如果你已经试过了,却想不出任何未来的可能性。你可以简单地说,你想不出任何东西。 请注意,在未来可能性部分写下一些东西并不是接受当前或未来RFC的理由;这样的说明应该放在动机或理由部分。 在这个或以后的RFC中的动机或理由部分。该部分只是提供额外的信息。
在这里提供你的项目需要什么样的贡献的信息。例如,这些可以是错误报告,帮助回答用户问题,改进文档,修复错误,以及新功能的实现。
在这里添加关于如何提交错误报告的信息。这应该包括提示项目需要哪种类型的信息,以便重现和修复问题。它还可以包括常见的看起来像bug的错误配置的信息。
也可以包括关于贡献者在首次回应和之后的处理方面可以期待的信息。
在这里添加关于如何提交功能请求的信息。也包括关于贡献者在首次回应和之后的处理方面可以期待的信息。
包括关于你的项目所遵循的任何文档最佳实践的信息,以及如何构建文档、运行检查和如何将所做的修改提交给项目。
本节应包含以下信息
如何访问项目的源代码。
一般的项目布局。
对开发环境的任何要求。
代码格式和风格指南。
如何运行测试套件。
如果成为Trusted Committers的途径对贡献者是开放的,那么这一节应该明确解释成为Trusted Committers的过程。
这一节是对现有Trusted Committers的提醒,也是向新的Trusted Committers提供详细解释,如何增补其他人到项目拥有者团队中。理想情况下,本信息也应该适用在组织中的所有项目,因此本信息可以作为统一的定义已链接的形式引用。