我们正在升级FutureStack的注册,仅到4月30日。条款和条件适用。 现在注册

初学者的开源指南,第4部分:如何开始和发展开源项目

7分钟阅读

通过Vi Tran

这是一个由四部分组成的系列中开始使用开源项目开始。

开源曾经被认为是工程师们展示他们的项目和专门社区的地方,现在它已经被几乎每一个开发人员所使用、鼓励和喜爱。如今,在GitHub或GitLab上拥有一个活跃的作品集是求职时很重要的一件事,同时也能显示你如何回馈开发者社区。

因此,许多开发人员都有兴趣开始成功的开源项目。虽然对现有的项目做出贡献是另一种选择,但将自己的项目推向世界会带来更有益的学习曲线。开源项目的大多数方面与源代码无关。看看一些最成功的开源回购,您可以看到这些项目是繁荣的社区。

在本文中,我们将查看开源项目的五个提示 - 这些成分将使您的项目协作,可理解和邀请。

1.从一个伟大的自述开始

在GitHub中,README文件是存储库的描述性文档。这些文件通常用信息性图形和横幅装饰,以及链接,代码片段和其他有用的信息。

项目存储库中的主README是大多数开发人员首先看到的东西。看看其他的开源项目,你会很快发现一个你应该包括的常见结构:

  • 一些信息横幅(构建状态,包管理器链接,许可证,覆盖范围等)
  • 名称和项目目标
  • 如何使用该项目(“入门”)
  • 一些(简单的)使用项目的例子
  • 如何贡献(有时与贡献者指南)
  • 有用的链接
  • 项目许可(例如,MIT,Apache)

信息横幅可以是这样的:

通常,它们应该包括最相关的链接和状态指示器。

在介绍项目时要简明扼要。用简单、直接的句子清楚地说明如何快速起床和跑步。

当您介绍图形应用程序(例如,桌面应用程序)时,在README中包含屏幕截图,显示在用户导航到适当位置时屏幕应如下所示的屏幕截图。如果您已编写控制台应用程序,则某些输出代码片段将帮助用户确认一切正常工作。工具喜欢asciinema对于快速显示发生了什么至关重要。一个在YouTube上托管的演示视频的链接,或您喜欢的视频平台,也将帮助指导用户通过设置过程。毕竟,你的README应该包含许多学习风格。

您的项目是一个库,应用程序还是只是一组数据,包括在所有相关平台上使用或安装它的说明。如果不支持某个操作系统,请明确提及此。通常,具有支持的框架,标准或系统的矩阵是有帮助的。这也是通过传达您的愿景来获胜新贡献者的机会。

2.不要跳过文档

您的自述文件应包含简单的示例,并提供进一步文档的链接。很棒的文档可能听起来像一个额外的可选项目组件。但是,文档是将项目与其他人区分开来的因素。

如果您查看一些最受欢迎的开源项目,您会发现他们有详细的文档。如果没有人能弄清楚如何使用它,那么你的代码有多棒并不重要。理想情况下,您应该包含使用代码显示项目用例的示例项目。

这样想:如果你对这个项目一无所知,你什么都需要什么?您需要知道全部深度的项目用例吗?如果文档可以回答这些问题,它为项目社区形成了坚实的基础。

3.公开跟踪问题

构建软件是一个持续的过程,公开跟踪问题可以让潜在的贡献者看到您的待办事项列表。其中一些问题只是表面问题,而另一些则是影响性能的bug。有些问题可以在几秒钟内解决,而另一些则更难处理。有时工作区存在;有时需要热修复。

然而,如果没有公共问题跟踪器,就没有人可以看到。没有人可以提供或提供变通方法。这个问题是否影响到许多用户?有人能帮助提供一个热修复程序吗?没有人期望没有问题的软件,但人们确实期望社区的开放和透明。

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

4.添加贡献者指南

为了鼓励新的贡献者提交拉拉请求(PR),为您的项目添加贡献者指南有助于。一个指导为学习他们需要做些什么来贡献项目的地方。例如:

贡献者指南应该包括样式指南、编码标准、测试需求和关于提交拉请求的说明。

包括一个行为准则,以使项目适当的框架。为种族主义或令人反感的讲话等反社区的东西留下没有地方。鼓励友好,专业的讨论,新人被接受和耐心地引导。

5.有一个好的第一个问题清单

GitHub的良好的第一个问题列表显示问题的有用功能:标签。标记更容易的错误或功能请求是有用的,作为良好的初学者问题。这些范围内容很小,并且可以让新的开发人员到项目解决。

这些“第一期”项目为有兴趣的开发人员提供了一个艰难的开支,成为项目的新贡献者。一旦他们解决了一个或两个简单的问题,他们就会准备好接受更复杂的任务。

对于所有的问题,清楚地描述为什么这些问题存在。对于新功能,添加一些背景信息,以了解添加该功能的一般动机和潜在步骤。对于bug,请描述如何重现bug以及期望的行为是什么。如果已经知道了解决bug的副作用,也要包括它们。

除了问题分类之外,您还应该使用标记来指示功能区域、严重程度(对于bug)和当前状态。例如,物品是已经被人抢了还是还在待价而沽?或者已经有一个预览版的解决方案了?

您还可以利用里程碑充分通知用户何时需要修复bug或功能。

下一步

当开始一个开源项目时,你不只是在网上发布项目;你正在创建一个社区。

社区建设很少是偶然发生的。这通常需要共同的努力。虽然不是每个项目都能吸引社区,但为社区发展提供一切的基础在很多方面都是有帮助的。

拥有所有必要的钟声和吹口哨肯定是很大的,但如果尚未知道,没有人会使用该项目。当您完成基础时,是时候告诉社区有关您的项目。与朋友开始或使用您的同事找到第一个合作者,并在它上获得关键(但通常仍然是积极的)。使用势头来发布关于社区网站,通讯,论坛和其他相关地方的项目。

有关我们的开源项目的更多信息,请查看新的遗物开源。并且随意填写问题或在您在那里提交拉出请求。我们一直在寻找贡献者。