如何让你的开源项目对新来者更友好

开源项目| 2016-01-12

我喜欢开源项目的一个原因是它可以让新手获得一些十分有用的实战经验。对于小的个人项目来讲，可以学习的就是那么多；但是开源项目就不一样了，它经常需要在很庞大的代码中解决问题，这些问题通常在小型或者个人项目中不会出现。当然还有一些合作上的技巧值得学习。

因为如此，我会在做项目的过程中更多的关注一下新手，也让他们能够从中学到一些经验。我挑选了一些技巧介绍，这些技巧并不是我的发明，而是从 Josh Matthews，Margaret Leibovic，Mike Conley和 Joel Maher 等人做事过程中观察学习到的。如果你感兴趣，可以看一下 Margaret 写的这篇博客，还有 Josh 的演讲 PPT。

在我开始之前，我想说的是让一个项目“对新来者友好”不是什么魔术，它需要你花一些精力来让贡献者更加积极的参与到项目中，并有可能让某些人成为共同维护者，花这些精力真的值得的。

一件小事

有很多小事可以帮助你的项目获得贡献，很多也是显而易见的：

CONTRIBUTING.md

添加 CONTRIBUTING.md 文件。保持更新，并把它链接到 README 的显眼位置。README 文件应该还需明确详细的介绍如何构建项目。这两个文件是不同的，README 是给那些想要使用项目的人准备的（也许还需要包含如何从源码构建的信息），CONTRIBUTING 是给那些想要做贡献的人看的。

如何做出贡献: 如何发送一个补丁或者发起 pull request，在做之前检查以下事情（是否通过测试，是否按照要求提交等等）。还可以加入一些小技巧（比如添加一个内部文档的链接等），这可以让新的贡献者获取帮助，一个讨论的频道也是很有效的（IRC，Slack，Gitter 等都行）。如果你为你的问题列表加了标签，添加对标签的解释能够帮助找到合适的贡献者。一个对文件夹的简单解释也能够起到效果。

这里有一些例子，看看 servo 和 rust-clippy 的 CONTRIBUTING.md 文件。

维护一个简单 bug 的列表

再多说一点，用标签来标注简单的 bug。我喜欢 Josh 的一页幻灯片：

如何有礼貌的说去＊＊的
“在 bug 跟踪里面找点事情做。” – 所有项目维护者

大多数在 bug 问题跟踪列表里面的 bug 都很重要，充满了术语，缺少一些 bug 重现的方式，甚至让新加入的贡献者无从下手。虽然这样对于维护者来说比较“容易”写，但是对于 bug 的组织却是十分低效的，尤其是对于那些不太熟悉此项目的人来说。

大多数情况下，你只需要在 Github 上加一个标签，并且要记得将其连接到 CONTRIBUTING.md！

沟通!

保持一个畅通的沟通渠道。IRC 虽然让新来者首次使用感到不太习惯，但是它通常是却是大家喜欢的。如果你用 IRC，看看你是否能连接到一个 web 客户端（比如 Mibbit），最好有一个简单指引。Gitter 也同样受到大家的喜爱。

邮件列表也可以，所有人都知道怎么发邮件吧！但是新来者有点不敢用它，大家都怕自己的问题太二却让大家都看到了。

一个明确的有启发性的问题对问题的解决很有帮助。Clippy（项目太小）没有官方邮件列表也没IRC频道，但是我鼓励大家在任何地方向我反馈 bug，我用过邮件、GH、IRC 甚至 Reddit 的私信，它们都不错。

通常人们也会给你发私信寻求帮助，给予帮助的同时鼓励大家在官方主频道提问。这有双重好处，第一可以告知大家主频道欢迎大家提问，第二当你不在的时候问题也能被其他人回答。

认可

欢迎新的贡献者。发一条关于他们的Twitter，接受一个只有两行代码改动的提交，看起来微不足道，但是一旦你这么做了，你会感觉很开心，会让项目看起来更棒。Rust周报和Servo周报都会提及贡献者，有时我也会在Twitter提及，同时我会收到来自被提及者的开心的回信。

增加行为规范

很多人在与他人网上交流的时候都有过不好的经历，通常在其它的开源社区，这也导致他们再加入社区的时候很谨慎。一个行为规范就是一个针对让人生厌行为的声明，它可以帮助项目受到欢迎和吸引人们的加入，进而让其成为一个可以帮助别人的好去处。当然，如果必要的话，你应该准备好执行这个行为规范。

我使用Rust行为规范，但是贡献者条约也不错。不同的社区有其自己的规范，选一个适合的就好了。

设身处地!

我们大概忘记了现在做的事情的开始阶段有多困难，对我们来说pull request已经几乎成为了第二本能。

但是不是所有人都习惯这些事情。我就看过一些贡献者，他们代码写的很好，但是没有用过Github，所以在做pull request的时候遇到了很多困难，在类似的流程上面也是一样，比如代码审查、版本控制¹、针对性的构建。

时刻想着，曾经经历过的新贡献者他们上手就很快，那些经验不足的自然会问你很多问题。

提高新来者的体验

那么现在假设你已经把基本的东西搭建好了，让人们对于贡献代码有了一个大致的了解。接下来讲讲更具体的内容。

引导

不要只是留一个简单的bug让别人修复，要引导性的修复！这会给贡献者带来乐趣，并且获得宝贵的经验，同时他们有可能会去更多的了解你的项目，从而让他感觉到自己是很有价值和受到欢迎的。

最好更进一步的在别人还没有了解的情况下给予一下指引（例子）。开源项目的沟通通常有一些延迟，贡献者很有可能和你在星球的两端，或者和你在不同的时间段贡献代码²。减少这种来回的沟通是很有帮助的，提供一些有用的信息可以帮助贡献者在没有获得你的答复之前找到解决的办法，这也会增加他们的经验。

千万不要在自己还没弄懂如何修复的时候去引导别人。理想情况下，你应该在给出指导性建议之前，就知道修复bug的确切步骤。不要说得太过具体，但是你应该自己去尝试去解决一下（不写代码），从而保证不会有隐藏的陷阱。

好的关系就是，回答问题然后给予指导性建议，要在第一时间给大家传递一个信号就是问题是受欢迎的。有一些人，尤其是学生在加入开源项目的时候被吓到了，所以尽量保持沉默。这不好，为了健康的发展，你需要他们提出问题，鼓励他们提问，越多越好。

记住，大多数情况下，新来着就是被你本人吓到了。举个例子，我经常碰到一些我介绍进来的 Firefox 的贡献者，他们直接问我问题，而不是分配给他们的直接导师，他们的理由是“这些导师在 Mozilla 工作，对这个 bug 来说，问他们有点小题大做了”。当然这个理由不是他们的导师说的，他们都是很好而且乐于帮助的人，这是贡献者他们自己总结的，这个问题的出现没准就会让一个人遇到困难的时候不好张口。

一个解决办法就是，鼓励他们在项目的主频道提问。当一个人给我私信的时候，我会解答他们的问题，但是我会鼓励他们下次在主频道提问。这对所有人都好，它给频道带来了一种“请随意在这里问问题”氛围，（如果别人看到这个问题以前遇到过），那么我不在的时候也会分配给其他维护者帮助其解决问题。

当贡献者把一个 bug 给解决了，这种关系并没有结束，而是一个开始！你可以再看看代码中是否有类似的其它问题，也去认识一下这个贡献者，多跟他接触以消除他的恐惧心理。

适应新来者

大多数开源项目都有自己接受pull request的流程，这对于项目的健康发展和现有的贡献者来讲都是必须的，但是有可能会吓到新来者，同时这些流程有可能带来多余的沟通步骤。我就曾经遇到过，更新已经快做好了，但是经过几个流程之后，人不见了；还有代码已经写好了，但是因为流程问题最终没有被融合进来。这是很伤人的，简化多余的流程可以减少这种问题的发生。

举个例子，Servo使用Reviewable来做代码审查，日常贡献者使用它没有遇到什么问题，所以我们倾向于使用它。但是对于新来者提供的较小的pull request，我不会使用它，而是使用Github提供的界面就足够了。对于那些不需要Reviewable特性的pull request，我就会将其省略，从而让贡献者少走一个流程。

类似的，在 rust-clippy 项目上，我经常做一些小的修复，而且运行上传脚本，从而让贡献者少做一些步骤。我通常会在本地查看 pull request，运行 git merge pr-branch –no-commit –no-ff³，做一些修改，然后写上注释，就提交了。这么做的话 pull request 仍然会被标记为合并（commit –amend 就不会），历史信息也很明白。

OpenSSL 仍然使用邮件列表完成更新，但是他们也允许贡献者们利用 Github。做得久了的贡献者坚持使用邮件列表，但是新来者利用 Github 界面来完成操作的行为也是被允许的，尽量减少摩擦。

当然，为了新来者而削减流程应该只是在他们第一次或者第二提交的时候，要在日后不断的引领他们来按照要求的流程来做。

另外一种解决这个问题的办法就是带他们走一遍流程，建立一个非常小的 bug，也许只是字符串的替换，让他们按照流程提交上来。有了初次的经验，他们以后就会按照流程来做了，从而能够让他们更多的去关注实际的代码。

建立简单的bug

在开源项目中的另一个问题是，人们想对其贡献代码，但是没有找到合适的足够简单的bug。

我的经验是，寻找那些独立的而且不是特别重要的点来生成一个简单的bug，这帮助我找到了很多。比如那些需要润色的部分或者一些小的特性，不需要提交在主pull request流程中的代码。你也要给他们找出来，并且大胆的建立一个 bug，这也是需要时间来解决的。

举个例子，在我解决表单问题的时候，我不是把所有的问题一次解决，而是解决了必须的，还建立了一个简单的bug。这是另外一个类似的情况，我完成了表单提交的框架，并让其在<input>标签下面工作了，之后我为<button>标签建立了一个简单bug。

有时候，你找不到一个可以分割出来的小特性，但是你可以找到一些可以改进的地方。这就是个例子，我在做一些其它事情的时候发现的，我本可以花一点精力就可以将其做得更好，但是我没有自己做，而是建立了一个小 bug。

简单的重构也可以提炼出一些简单 bug。这虽然需要熟悉编程语言，但是也不用太多，而且这对于新来者也是很不错的。

也可以将一个复杂的 bug 让其变得简单一些，或者进行拆分。可以提供足够的提示（包括参考代码，详细说明等），把最难的部分都说清楚。

不要把重要的部分（比如说需要 1 到 2 个星期完成的）定义为简单 bug。对于新来者来说，简单的改变都有可能影响全部（比如沟通的不连贯、时间不能保证或者陷入僵局等）。简单 bug 应该是那些不急需的，可以花费很长时间来解决的问题。如果由于问题需要尽快解决，维护者帮助新来者修复了bug，这对新来者的伤害是很大的。（给予新来者一些不经常出现的 bug 供其解决，如果真的遇到急需的情况，就重新分配一个 bug 给新来者，并向他们道歉。）

洞察力

让新来者能够轻而易举的找到他们想要解决的 bug，而不是所有的简单 bug！

呦！有 bug 和我能为 Mozilla 做什么都是一些很棒的例子，Servo 也提供了给 Servo 的新来者的 bug 列表。

还有很多站点可以用来列出简单 bug，有一些罗列在 Emily 的博文中。

项目以及更深入的参与

建立一些简单 bug 以及让新来者参与进来只是其中的一步，你可能想要这些新来者做一些更复杂的工作或者项目，最好还能偶尔维护以及进行代码审查！

对于很多人，也许这并不需要你过多的参与。我遇到一些很专业的开发者，他们并没有过多的参与项目就变成了维护者，因为他们有足够经验通过自己就能了解整个项目的进展。

尽管如此，很多贡献者都是还是学生或者经验并不丰富，但是通过通过参与到你的项目中，他们逐渐变成了一个更好的开发者，通过一些努力可以让他们成为项目当中宝贵的一员。

鼓励他们去挑战一些更难的 bug 或者项目。维护一些“学生项目”（不是特别关键，但是需要人力来完成）也是很重要的，这些项目可以供贡献者来挑选，有时候他们可以做一些项目来赢得他们的学分。

不要随便挑选一些 bug 交给贡献者来做，找出并且提供一些逻辑上有关联的问题也是非常重要的。这样，贡献者可以专注于某部分代码，并且从这部分代码切人到整个项目。如果这部分逻辑能够引领贡献者到一个很大的功能，那就更好了。

Joel Maher 和 Mozilla 工具组发起了一个很棒的叫“季度贡献”的计划，它提供了对于某些项目的专项指导，目前运作的还不错。Google 代码夏令营、Outreachy 等项目也为贡献者们提供了一些途径，可以在某种程度上参与到你的项目中来。

创建这样的项目或者高难度 bug，是一个重要的问题，在（除了使用相似的技术“创建简单的 bug”一节中列出）那样，我在那个事情上并没有明确的想法。有想法我们欢迎。

在这里，项目并不总是必要的。这件事取决于贡献者，有时，你可以定期（不是简单地指定）解决一些问题，有一些暗示，来告诉他们试着不需要帮助的情况下（或是很少帮助的情况下）找出这些东西。这里鼓励他们问别人问题或发起讨论，但是要试着坚持观察。查看由其他人所指出的问题是很有意思的。我做的这个是与贡献者相关的东西，在那里我只提供了最初的暗示和代码评论。而在这里，我会鼓励操作者在没有我参与的情况下，直接启动有关于 bikeshedding 的各种渠道。现在的贡献者通过 Rust 社区和代码库将会有更多的联系，对我来说我很喜欢看着他们指出问题并直接进行讨论。