开源项目的最佳实践

  • Sergio De Simone
  • 邵思华

2015 年 12 月 11 日

话题:开源最佳实践GitHub语言 & 开发文化 & 方法

来自 GitHub 的Phil Haack在 Channel 9 网站上举办了一次座谈会,专注于谈论开源项目的最佳实践。

本次会议的四位与会者都是开源项目的维护者,包括来自微软拉美区的听众布道经理(Audience Evangelism Manager)Carlos Rojas,用于创建松耦合、可维护、易测试的 XAML 应用的PRISM 框架的作者Brian Lagunas,参与了多个开源项目工作的David Paquette,以及适用于 C# 及 VB 的分析器库CodeCracker的维护者Carlos dos Santos

Haack 为与会者所提出的第一个话题是:对于那些希望加入自己的开源项目的开发者们,他们有哪些期望?Lagunas 认为,提交 issue 是一种与项目的维护者开展对话的重要方法。Rojas 则指出,对于希望为项目作出贡献的开发者,首先浏览一遍未解决问题的列表也非常重要。他们两位都提到了一种非常实用的相关实践,即为某些未解决问题打上一个“随意领取”的标签,愿意参与这个项目的开发 者都可以领取这些问题。现在甚至还出现了一个“随意领取”的网站,那些潜在的贡献者们可以在此查到来自多个开源项目的各种可“随意领取”的未解决问题。Dos Santos 表示,对他来说,重要的是贡献者们能够为项目提交及修复 bug,并且切实地用到这些项目。

所有与会者们都认为,贡献者应当避免将代码直接提交并推送至 master 分支。正确的做法是提交一个 pull 请求(PR)。Lagunas 谈论了这方面更多的细节内容,他所期望的方式是贡献者能够创建一个属于自己的分支,在其中实现某些特性或进行 bug 修复,然后添加相应的测试代码,最后再提交 PR。到了适当的时机,这个 PR 将通过某种集中式的筛选操作进行测试,一旦它通过了所有的测试,维护者就将组织一次复审,以确保其中的代码变更符合项目的标准。

dos Santos 表示,为了帮助贡献者们,保证他们的 PR 符合项目的标准,可以在项目的根目录中加入一个 CONTRIBUTE.md 文件,这种做法非常实用。Haack 也指出,如果项目中已有 CONTRIBUTE.md 文件存在,那么在贡献者提交 PR 时,GitHub 就会自动显示一条信息,提醒贡献者去阅读该文件。Lagunas 特别强调了仔细阅读 CONTRIBUTE.md 文件的重要性,因为它有些时候会包含一些重要的内容,而这些内容并不局限于代码标准。举例来说,Prism 项目要求贡献者通过一个永久的、不可撤消的贡献者许可协议(Contributor License Agreement),放弃所贡献代码的所有权,将其转交给该项目所有。如果贡献者本身就受雇于某些公司,那么这一点就变得尤为重要,因为说不定有贡献者会回头宣称他对于该项目拥有知识产权。总的来说,与会者都认为,项目的许可条款必须明确定义,这一点十分重要。Paquette 还特别强调,这种重要性不仅限于贡献者,同时也包括项目的潜在用户。

Haack 又将讨论的方向转回了原来的话题上,即如何确保 PR 不会对项目产生破坏。Lagunas 提到了适用于.NET 平台上的开源项目的一个免费服务appveyor,可以通过该服务对每个 PR 进行构建与测试。Haack 进一步表示,只要你的 GitHub 项目中没有什么特别古怪的问题,那么 appveyor 通常都能够正确地处理项目的各种依赖。

另一个让人感兴趣的话题是项目的文档。Rojas 表示,在项目中最低限度也要提供一个 README.md 文档。Haack 以 Prism 的文档作为示例,指出编写项目文档的正确方式,即通过 readme 文件说明总体情况,然后再通过其它文件描述各种细节。Rojas 还提到了 GitHub 所提供的另一个工具 wiki,他认为可以通过使用 wiki 有效地建立文档。

随后话题转向了开源的文化。开源社区在这方面存在着一个问题,如果贡献者出了某些差错,有时可能会换来一些粗暴的回应。与会者们都认为:应当以良好的态度对待贡献者,认识到这些贡献者们的出发点是帮助这个项目。尤其某个 PR 或许是这个开发者第一次为开源项目贡献代码,那么项目维护者的沟通方式就可能会直接影响到这名开发者今后看待开源项目的态度。

最后,所有的与会者们都表示,贡献者们应当努力尝试克服胆怯的心态,去寻找那些能够点燃自己激情的项目。不要忘记,开源的核心是协作。有许多人对于他们所维护的项目充满了热情和感情,尤其是看到有人在实际使用他们的项目,或是为这些项目作出贡献时。

查看英文原文:Best Practices for Open-source Projects

开源最佳实践GitHub语言 & 开发文化 & 方法