开源初学者指南（四）：如何启动和发展一个开源项目

原文：The Beginner’s Guide to Open Source, Part 4: How to Start and Grow an Open Source Project 作者：Vi Tran，编译：御坂弟弟

开源曾经被认为是工程师展示自己项目和社区的地方，经过发展，现在几乎每个开发者都在使用、鼓励和喜爱开源。如今，在 GitHub 或 GitLab上 活跃的作品集是申请工作时的重要内容，同时也是你如何回馈开发者社区的证明。

因此，许多开发者都对创办成功的开源项目感兴趣。虽然为现有的项目做出贡献也是一种选择，但将自己的项目推向世界则会有一条更有价值的路线。开源项目的大多数方面都与源代码无关，目前，最成功的开源项目往往不仅是代码仓库，而且是一个正蓬勃发展的社区。

本文将介绍启动开源项目的五个技巧，来帮助使你的项目具有协作性、可理解性和吸引力。

从一个好的 README 开始

在 GitHub 中，README 文件是一个仓库的描述性文档。这些文件通常用信息丰富的图形和横幅装饰，包含链接、代码片段和其他有用的信息。

一个项目仓库中的主 README 是大多数开发者首先会看到的东西。通过观察其他的开源项目，我们会发现其中有一些相同点。

• 一些信息性的横幅(构建状态，包管理器链接，许可证，覆盖范围等等)
• 名称和项目目标
• 如何使用该项目。
• 一些使用项目的简单例子
• 如何投稿
• 有效链接
• 项目许可证（如 MIT、Apache）

信息性的横幅如下所示：

通常，它们应该包括最相关的链接和状态指标。

在介绍项目时要简洁，注意用简单、直接的句子给出如何快速启动和运行的明确说明。

当你介绍一个图形化的应用程序（例如，一个桌面应用程序）时，应该在 README 中提供相应的屏幕截图。如果你写了一个控制台应用程序，则应该提供一些示例代码片段。像 asciinema 这样的工具可以帮助快速显示正在发生的事情。此外，加入在 YouTube 或你喜欢的视频平台上托管的演示视频的链接，也将有助于完成用户引导。总而言之，你的 README 应该包容多种简明合理的样式。

无论你的项目是一个库，一个应用程序，还是仅仅是一组数据，都要包含在所有相关平台上使用或安装的说明。如果不支持某个操作系统，请明确指出。通常情况下，一个包含支持的框架、标准或系统的矩阵是很有帮助的，这也是一个通过传达你的愿景来赢得新贡献者的机会。

不要跳过文档

README 应该包含简单的例子，并提供相应文档的链接。优秀的文档听起来像是一个额外的、可选的项目组件。然而实际上，文档是让你的项目有别于其他项目的关键因素。

如果你关注一些最流行的开源项目，你会发现他们通常有详细的文档。如果没有人能够弄清楚如何使用你的代码，那么无论你的代码有多好也无济于事。理想情况下，你应该包含使用你的代码的示例项目来展示项目用例。

可以这么理解：如果你对这个项目一无所知，你需要什么信息才能开始？要全面深入地理解项目的用例，你需要知道什么？如果文档能够回答这些问题，那么它就为项目的社区奠定了坚实的基础。

公开跟踪问题

构建软件是一个持续的过程，公开跟踪问题可以让潜在的贡献者看到你的待办事项列表。这些问题中有些是表面上的，而有些则是影响性能的 bug。有些问题可以在几秒钟内解决，而有些问题则比较难解决。有时存在变通办法，有时需要热补丁。

然而，如果没有一个公开的问题跟踪器，就没有人可以看到。没有人可以贡献或提供变通办法。这个问题是否影响到许多用户？是否有人可以帮助提供一个热补丁？ 没有人会期望软件没有问题，但人们由衷期望社区能提供公开性和透明度。

最终，仅仅是公共问题的存在就可以帮助你发展一个项目，这表明你正在积极维护你的项目并寻找贡献者。另一个原因是，人们需要有一个类似问题或活跃工作项目的平台来贡献。

添加一个贡献者指南

为了鼓励新的贡献者提交拉取请求（PR），你应该在项目中添加一个贡献者指南。指南为有兴趣的贡献者提供了一个了解他们需要做什么才能为项目做出贡献的地方。比如：

贡献者指南应该包括风格指南、编码标准、测试要求和提交拉取请求的说明。

此外，贡献者指南也要包括行为准则，给项目发展定一个适当的框架。不给反社区的东西留位置，比如种族主义或攻击性的言论，而是鼓励友好的、专业的讨论，这会帮助新人受到欢迎和耐心的指导。

有一份好的入门清单

GitHub 的入门清单表显示了问题的一个应用方法：标签。将比较容易的 bug 或功能请求标记为好的初学者问题是很有帮助的。这些问题范围较小，对项目的新开发者来说很容易解决。

这些 “入门问题” 项目为有兴趣的开发者提供了一个途径，让他们成为项目的新贡献者。一旦他们解决了一两个简单的问题，他们就可以接受更复杂的任务了。

对于所有问题，都要清楚地描述这些问题存在的原因。对于新功能，应该添加一些背景信息，以让贡献者了解一般的动机和添加功能的潜在步骤。对于 bug，应该描述如何重现 bug 以及预期的表现是什么。如果已经知道解决 bug 的副作用，也要包括进去。

除了问题分类，你还应该使用标签来表示功能区、严重性（对于 bug）和当前状态。例如，这个问题是否已经有人在解决？或者解决方案是否已经在预览版本中可用？

你也可以利用里程碑来充分告知用户何时会有 bug 修复或某个功能。

下一步

当启动一个开源项目时，这不仅意味着是在网上发布项目，也意味着正在创建一个社区。社区建设很少是偶然发生的，它通常需要协调一致的努力。虽然不是每个项目都是向社区发展的，但提供一切发展社区的基本要素在很多方面都有帮助。

拥有适当的名声是必要的，如果这个项目寂寂无名，就没有人会使用它。当你完成了基本的工作后，是时候把你的项目告诉社区了。从朋友开始，或者利用你的同事找到第一个合作者，并获得对它的批评（但通常还是积极的）看法。利用这个势头在社区网站、通讯、论坛和其他相关的地方发布关于项目的消息。