开源中国

我们不支持 IE 10 及以下版本浏览器

It appears you’re using an unsupported browser

为了获得更好的浏览体验,我们强烈建议您使用较新版本的 Chrome、 Firefox、 Safari 等,或者升级到最新版本的IE浏览器。 如果您使用的是 IE 11 或以上版本,请关闭“兼容性视图”。
如何让你的开源项目对新来者更友好 - 技术翻译 - 开源中国社区

如何让你的开源项目对新来者更友好 【已翻译100%】

标签: <无>
oschina 推荐于 2年前 (共 17 段, 翻译完成于 01-07) 评论 2
收藏  
71
推荐标签: 待读

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

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

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

drkaka
 翻译得不错哦!

一件小事

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

CONTRIBUTING.md

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

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

这里有一些例子,看看 servorust-clippy 的 CONTRIBUTING.md 文件。

drkaka
 翻译得不错哦!

维护一个简单 bug 的列表

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

        如何有礼貌的说去**的

        “在 bug 跟踪里面找点事情做。” 
                                           - 所有项目维护者

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

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

drkaka
 翻译得不错哦!

沟通!

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

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

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

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

drkaka
 翻译得不错哦!

认可

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

增加行为规范

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

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

drkaka
 翻译得不错哦!

设身处地!

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

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

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

提高新来者的体验

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

引导

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

drkaka
 翻译得不错哦!

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

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

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

drkaka
 翻译得不错哦!

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

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

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

drkaka
 翻译得不错哦!

适应新来者

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

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

drkaka
 翻译得不错哦!

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

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

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

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

drkaka
 翻译得不错哦!
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们
评论(2)
Ctrl/CMD+Enter

good
收藏了
顶部