新人必看的开源指南：如何参与并做贡献

想为开源做贡献吗？这是一份写给新手和老手的开源贡献指南。

第一部分：为何要为开源做贡献？

在 freenode 的工作使我学到了很多技能，后来我将它们运用到我的大学学习和实际工作中。我认为在开源项目中的工作对我的帮助和它对项目本身的帮助一样大！— @errietta，《为什么我热爱为开源软件做贡献》

为开源做贡献是学习、教学和在你能想象的任何技能上积累经验的有益途径。

为什么人们为开源做贡献？有许多理由！

提升现有技能

不管是写代码、用户界面设计、平面造型设计、写作，或是规划，如果你在寻找实践机会，在开源项目中总有适合你的任务。

结识爱好相似的人

拥有热情而友好的团体组织的开源项目使人们在多年以来常常回访。许多人通过参与开源成了一辈子的好朋友，无论是在会议中碰面还是深夜里线上聊玉米煎饼。

找到导师和教导他人

在共享的项目中与他人一起工作，意味着你必须解释你做事的方式，此外还要寻求他人的帮助。学习和教导，对参与其中的所有人都是一种满足的活动。

开发公开作品，帮你提升声望（和事业）

根据定义，你的所有开源工作都是公开的，这意味着你得到了免费的样本，可以带到任何地方，作为你能做事情的证明。

学习交际能力

开源提供了练习领导才能和管理技能的机会，比如解决冲突、组织不同团队的人，和给工作排优先级。

人人都可以参与改变，不分大小

你不一定要成为终生的贡献者才能享受参与开源的乐趣。你是否曾在网站上看到一个拼写错误，希望某人会修正它？在开源项目中，你就能做到这点。开源帮助人们在他们的生命中和他们对世界的体验中感受到力量，这本身是令人满足的。

第二部分：贡献意味着什么

如果你是一个开源贡献方面的新人，这个过程可能是令人生畏的。怎么找到合适的项目？不会写代码怎么办？某件事出岔子了会怎样？

不用担心！有各种各样的方法参与开源项目，并且有几个诀窍会帮你最大程度地运用你的经验。

你不一定要贡献代码

关于为开源做贡献，一个常见的误解是你必须贡献代码。事实上，常常是项目中非代码的部分大多被遗漏和忽视了。通过参与提供非代码的贡献，你会给项目做出巨大的帮助！

我因为在 CocoaPods 中的工作出名，但大多数人不知道实际上我在 CocoaPods 工具本身上并没有做任何实际的工作。我在这个项目上花费的时间，大部分是在做诸如文档和品牌推广工作之类的事情。— @orta，《默认转向开源软件》

即使你是一名开发者，非代码贡献也是参与项目并结识其它团体成员的极好方式。建立那样的关系，将给予你在项目的其它部分工作的机会。

我初次接触 Python 开发组（也叫做 python-dev）是在 2002 年 6 月 17 日，我就接受我的补丁事宜向邮件列表发电子邮件。很快我发现了开源中的一个 bug，并决定把这个错误写成邮件摘要汇报给小组。我对这个主题做了澄清，他们为麻烦我做这件事而表示了大大的歉意。但更关键的是，当某人指出的某些东西需要修正时，我能够看到的。— @brettcannon, “Maintainer Stories”

你是否喜欢活动规划？

• 组织关于项目的专题讨论会或聚会，就像 @fzamperin 为 NodeSchool 所做的那样。
• 组织项目会议（如果他们有的话）
• 帮助团体成员找到合适的会议并提交演讲提议

你是否喜欢设计？

• 调整布局以提高项目的可用性
• 做用户调查以重新组织和改善项目的导航和菜单，就像 Drupal 建议的那样。
• 制订风格指南以帮助项目拥有一致的视觉设计
• 为T恤或新的 logo 绘画，就像 hapi.js 的贡献者所做的那样。

你是否喜欢写作？

• 编写和改进项目文档
• 组织一个示例文件夹，展示怎样使用项目
• 开办项目通讯，或从邮件列表中组织重要内容
• 为项目编写教程，就像 pypa 的贡献者所做的那样。
• 翻译项目的文档

说真的，“文档”极其重要。到目前为止，Babel（Kittens 的开源项目）的文档一直很棒，已经成为了它的杀手级特性。但是肯定还需要做一些工作加以完善，甚至加一些段落上去，对此我非常感激。— @kittens，《需要贡献者》

你是否喜欢组织？

• 链接重复的工单（ Issue），给出新的工单（ Issue ）标签建议，让事情井井有条
• 检查开放的工单 ，提议关闭旧的工单 ，就像 @nzakas 为 eslint 所做的那样
• 在最近开放的工单中提有助于澄清的问题，把讨论向前推进

你是否喜欢写代码？

• 找一个开放的工单（ Issue ）着手处理，就像 @dianjin 为 Leaflet 所做的那样
• 问问你是否能帮忙写一个新特性
• 自动化项目的设置
• 提升工具和测试

你是否喜欢帮助他人？

• 在诸如 Stack Overflow（就像这个 Postgres 的例子一样）或 reddit 之类的地方回答关于项目的问题
• 在开放的工单（ Issue ）中为人们回答问题
• 帮忙主持讨论版或会话通道（conversation channels）

你是否喜欢为他人的代码提供帮助？

• 审查他人提交的代码
• 为如何使用项目写教程
• 为其它贡献者提供指导，就像 @ereichert 在 Rust 上为 @bronzdoc 所做的那样

你并不非得要在软件项目中工作！

虽然“开源”通常指软件，但你可以在任何事情上协作。有书籍、食谱、清单和课程是作为开源项目开发的。

例如：

• @sindresorhus 组织了一个 Awesome 的清单列表
• @h5bp 为前端开发求职者维护了一个可能的面试问题的清单
• @stuartlynn 和 @nicole-a-tesla 制作了一份关于 puffins 的有趣事实的集合

即使你是一名软件开发者，在文档项目上的工作也能帮你在开源方面起步。在与代码无关的项目中工作常常不那么令人生畏，而且协作的过程将增强你的自信和经验。 

第三部分：熟悉一个新项目

如果你去看一个工单（ Issue ）追踪器，发现事情看起来令人困惑，并不是只有你这样。这些工具需要大量的隐性知识，但人们能帮你驾驭它，你也能向他们提问。— @shaunagm，《怎样为开源做贡献》

对任何超过修正拼写错误的事情来说，为开源做贡献就像在社交聚会上走向一群陌生人。如果当他们正在深入讨论金鱼时，你开始谈论美洲鸵，他们可能有点奇怪地看着你。

在带着你自己的建议盲目投入以前，先从学习怎样观察聚会中的人，参与他们讨论的话题开始。这样做能增加你的想法被注意到和听取的可能性。

开源项目剖析

每个开源团体都是不同的。

在一个开源项目中花了若干年时间意味着你已经了解了一个开源项目。转向一个不同的项目，你可能会发现词汇、规范和沟通方式完全不同。

即便如此，许多开源项目遵循着相似的组织结构。理解不同的团体角色和总体过程将帮你迅速熟悉任何新项目。

一个典型的开源项目有以下几类人：

• 作者（Author）：创建该项目的人或组织。
• 所有者（Owner）：对组织或仓库（repository）拥有行政所有权的人（并不总和原始作者是同一个人）
• 维护者（Maintainers）：对推动愿景和管理项目的组织方面负有责任的贡献者。（他们可能也是项目的作者或所有者）
• 贡献者（Contributors）：每个对项目做出过某种贡献的人。
• 团体成员（Community Members）：使用项目的人。他们可能在对话中保持活跃或者对项目的方向表达他们的主张。

大的项目可能还有下属委员会或工作组，他们致力于不同的任务，比如工具、分类（triage）、团体节制（community moderation）和活动组织。在项目的网站上寻找“team”页面，或者在仓库（repository）里寻找治理文档（governance documentation），来找到此类信息。

项目也有文档。这些文件通常列在仓库（repository）的顶层。

• 许可证（LICENSE）：根据定义，每个开源项目必须有一个开源许可证。如果项目没有许可证，那它就不是开源的。
• 自述文件（README）：自述文件是迎接项目的新团体成员的操作指南手册。它解释了为什么项目是有用的以及如何开始。
• 贡献（CONTRIBUTING）：自述文件帮助人们使用项目，而贡献文件帮助人们为项目做贡献。它解释了需要什么类型的贡献者以及这个过程是怎么工作的。虽然不是每个项目都有贡献文件，但它的存在表明这是一个欢迎做贡献的项目。
  • 行动守则（CODE_OF_CONDUCT）：行动守则为参与者的相关行为设定了基本准则，并且帮助促进一个友好而热情的环境。虽然不是每个项目都有行动守则文件，但它的存在表明这是一个欢迎做贡献的项目。
  • 其它文档：可能有另外的文档，比如教程、演练或管理策略，尤其是在大项目中。

最后，开源项目使用以下工具来组织讨论。通读档案文件将为你很好地描绘该团体是怎样思考和工作的。

• 工单追踪器（Issue tracker）：人们讨论项目相关工单（ Issue ）的地方。
• 拉取请求（Pull requests）：人们讨论和审查进行中的更改的地方。
• 讨论板或邮件列表：有些项目可能为会话主题使用这些通道（例如，“我怎样……”或“你认为……怎么样”，而不用 bug 报告或特性请求）。其它项目为所有会话使用 Issue 追踪器。
• 同步聊天通道（Synchronous chat channel）：有些项目为临时会话、协作和快速交流使用聊天通道（比如 Slack 或 IRC）。

第四部分：找到一个要做贡献的项目

既然你已经弄明白开源项目是怎样工作的，是时候找到一个要做贡献的项目了！

如果你之前从未为开源做过贡献，听听美国总统约翰·F·肯尼迪的建议，他曾经说：“不要问你的国家能为你做什么-问问你能为你的国家做什么。”

为开源做贡献在所有层面和不同项目间都能发生。你不必对你的第一个确切的贡献是什么，或它看起来是什么样想得过多。

相反地，从考虑你已经在使用的或想要使用的项目开始。你会积极地做贡献的项目正是你发现自己会回访的项目。

在那些项目里，无论何时你发现自己想到某件事可以变的更好或不同，按照你的直觉行动吧。

开源不是一个排外的俱乐部；它是由和你一样的人做出来的。“开源”只是一个花哨的术语，为了把世界上的问题都作为可修正的来处理。

你可能会细看一份自述文件，发现一个断开的链接或一个拼写错误。或者，你是一个新用户，你发现某样东西毁坏了，或是一个 Issue 你认为实际上应该在文档中。与其忽略它并继续，或请求其他人修正它，不如看看你能不能参与帮忙。这就是开源的真谛！

对开源的非正式贡献中，有28%是文档，比如拼写错误修正、重排格式，或翻译。

你也可以使用下列资源之一来帮你发现新项目：

• GitHub Explore
• First Timers Only
• Your First PR
• CodeTriage
• 24 Pull Requests
• Up For Grabs
• Contributor-ninja

做贡献前的一份检查表

当你找到一个你想要做贡献的项目，做一个快速的浏览来确认该项目适合接受贡献。否则，你的努力工作可能永远得不到回应。

这是一份便于使用的检查表，用来评估一个项目对新贡献者来说好不好。

满足开源的定义

• 它有没有许可证？通常，这是在仓库（repository）根目录里的一个叫做 LICENSE 的文件。

项目积极地接受贡献

看看主分支上的提交活动。在 GitHub 上，你可以在仓库的主页上看到此信息。

• 最新的提交（commit）是在什么时候？
• 项目有多少贡献者？
• 人们提交频繁程度？（在 GitHub 上，你可以通过点击顶部横条里的 “Commits” 来找到此信息）

下一步，看看项目的工单（ Issue ）。

• 有多少开放的工单 ？
• 当工单开放时，维护者是否快速地回应？
• 对于工单有没有活跃的讨论？
• 工单是最近的吗？
• 工单是否得到关闭？（在 GitHub 上，点击 Issue 页面上的 “closed” 标签来看已关闭的 Issue 。）

现在对项目的拉取请求（ pull requests）做同样的动作。

• 有多少开放的拉取请求？
• 当开放拉取请求时， 维护者是否快速地回应？
• 对于拉取请求有没有活跃的讨论？
• 拉取请求是最近的吗？
• 拉取请求被合并是在多久之前？（在 GitHub 上，点击 pull requests 页面上的 “closed” 标签来看已关闭的 pull requests。）

热情的项目

友好而热情的项目标志着他们乐于接受新的贡献者。

• 维护者对于工单中的问题是否作出有帮助的回应？
• 人们在工单 、讨论板和聊天（例如 IRC 或 Slack）中是否友好？
• 拉取请求是否得到审查（reviewed）？
• 维护者对人们的贡献是否表示感谢？

无论何时你看一个长的讨论帖，抽查一下较晚进入这个帖子的核心开发者的反应。他们是否作出建设性的总结，在做出决策和付诸实施时，是否同时还保持礼貌？如果你看到发生许多口水仗，那通常表明精力用在了争论而不是开发上。— @kfogel，创作开源软件

第五部分：怎样提交贡献

你已经找到一个你喜欢的项目，并且你已经准备好作出贡献。最后！这里告诉你怎样以正确的方式作出你的贡献。

有效的沟通

不管你是一次性的贡献者或是试着加入一个团体，与他人一起工作是你将在开源中发展的最重要的技能之一。

作为一个新贡献者，我很快认识到，如果我想要能关闭工单 ，我必须提问。我浏览了代码库。一旦我对发生的事有了一些认识，我请求更多的指点。就是这样！在得到我需要的所有相关细节后，我能解答工单了。— @shubheksha，一个新手在开源世界中的颠簸旅途

在你打开一个工单或使用拉取请求，或是在聊天中提问以前，记住这些要点可以使你的想法有效地被别人理解。

给出上下文。帮助他人快速赶上进度。如果你遇到一个错误，解释你正准备做什么和怎么重现它。如果你提出一个新主张，解释为什么你认为它对项目有用（不只是对你！）。

 “当我做 Y 时 X 没有发生”
 “X 坏了！请修好。”

事先做好功课。不懂没什么，但要表现出你试过了。在求助之前，务必查看项目的自述文件、文档、 Issue （开放的或关闭的）、邮件列表，并且在因特网上搜索答案。当你证明你在试着学习时，人们会表示赞赏。

“我不确定怎么实现 X。我查过了帮助文档，没找到哪里有提到。”
“我怎么做 X？”

请求要简短而直接。和发送电子邮件很像，每一个贡献，不管多简单或多有帮助，都需要某个其他人的审查。许多项目收到的请求比能提供帮助的人多。简明一点。你会提高某人能帮到你的可能性。

“我想写一份 API 教程。”
“前几天我正在高速公路上开车，停下来加油，然后我对我们应该做的事情有了这个惊人的想法，但在我解释这个想法之前，让我向你展示……”

交流要对公众可见。尽管有点诱人，但不要私下联系维护者，除非你需要分享敏感信息（比如安全问题或严重的违反行为）。当你使对话对公众可见时，更多的人能从你的交流中学习并受益。讨论本身也可能是一种贡献。

（作为评论）“@-maintainer 你好！我们在这个拉取请求功能上怎么继续？”
（作为一封电子邮件）“你好，抱歉通过电子邮件麻烦你了，但我不知道你有没有可能审查我的拉取请求。”

可以提问（但要耐心！）。每个人在某个时刻都曾是项目的新人，而且即使有经验的贡献者查看新项目时也需要赶上进度。由此类推，即使长期贡献者也并非总是对项目的每个部分都熟悉。对他们表现出与你希望他们对你表现出的同样的耐心。

“谢谢你研究这个错误。我按你的建议做了。这是输出结果。”
 “为什么你不能解决我的问题？这不是你的项目吗？”

尊重团体的决定。你的想法可能与项目的优先考虑或愿景不同。他们可能提供反馈或决定不执行你的想法。你应该讨论并寻求妥协，而维护者必须花比你更长的时间适应你的决定。如果你不同意他们的方向，你总是可以致力于你自己的 fork 或启动你自己的项目。

“我对你不能支持我的用例感到失望，但既然你已经解释了它只影响一小部分用户，我理解为什么了。谢谢倾听。”
“为什么你不支持我的用例？这无法接受！”

最重要的是，要优雅。开源由来自世界各地的合作者组成。上下文在跨越语言、文化、地理和时区时会丢失。另外，书面交流使得传递语调或心情更困难。假设这些对话的意图都是好的。礼貌的把想法推后，要求更多的上下文，或进一步澄清你的态度，这些都是好的做法。使因特网成为比你发现它时更好的地方。

收集上下文

在做任何事之前，做一个快速的检查，确保你的想法没有在其它地方被讨论过。略读项目的自述文件、 工单 （开放的和关闭的）、邮件列表和 Stack Overflow。你不一定要花几个小时检查一切，但对几个关键词的快速搜索会大有帮助。

如果你在其它地方找不到你的想法，你已经准备好开始行动了。如果项目在 GitHub 上，你多半会通过开启一个 Issue（工单） 或使用 拉取请求（pull request ）来沟通：

• 工单就像开启一个会话或讨论
• 使用拉取请求是为了开始致力于一个解决方案
• 对于不重要的交流，比如一个澄清或操作方式问题，试着在 Stack Overflow、IRC、Slack 上提问，或是其它的聊天通道，如果项目有对应渠道的话

在你开启一个工单或使用拉取请求以前，检查项目的贡献文档（通常是一个叫做 CONTRIBUTING 的文件，或者在自述文件里），看看你是否需要把特定的东西包含进去。例如，他们可能要求你遵照一个模版，或是要求你使用测试。

如果你想做一个实质的贡献，在着手以前先开一个 Issue 提问。一个有帮助的做法是，在着手进行可能不被接受的工作以前，先对项目观察一段时间（在 GitHub 上，你可以点击 “Watch” 来获取所有会话的通知），并且了解团体成员。

找一个你经常使用的项目，在 GitHub 上“ Watch”它，阅读每个 Issue 和使用 pull request，你能从中学到很多。— @gaearon 参与项目

开一个工单

通常，在以下情况下你应该开一个工单 ：

• 报告一个你不能自行解决的错误
• 讨论一个高级的主题或想法（比如团体、愿景、策略）
• 推荐一个新特性或其它有关项目的想法

工单沟通的诀窍：

• 如果你看到一个你想着手处理的开放工单 ，在工单中作评论来让人们知道你在处理它。那样，人们就不太可能重复你的工作。
• 如果一个工单是一段时间以前开放的，可能它正在其它地方被处理，或已经被解决了，所以在开始工作前，在评论里要求做个确认。
• 如果你开了一个工单 ，后来自己想出了答案，在工单中作评论来让人们知道，然后关闭该工单 。即使对结果的文档化也是对项目的一种贡献。

使用拉取请求

通常，在以下情况下你应该使用拉取请求：

• 提交细小的修正（例如拼写错误、断开的链接或明显的错误）
• 对已经在工单中要求的，或你已经讨论过的贡献开始工作

使用拉取请求并不一定代表已完成的工作。在早期开一个拉取请求往往更好，这样其他人可以观察你的进展或给予反馈。只要在主题行里把它标记为 “WIP”（进行中的工作）。以后你总能添加更多的提交。

如果项目是在 GitHub 上，这是怎样提交一个拉取请求的方法：

• Fork 仓库并把它克隆到本地。通过把原始“上游”仓库添加为远程操作把它与你的本地连接。经常拉入（pull in）“上游”的改变，这样你保持在最新状态，这样的话，当你提交你的拉取请求时就不太可能出现合并冲突。（更详细的操作指南见这里。）
• 为你的编辑创建一个分支
• 在你的拉取请求中引用相关的工单或支持文档（比如，“Closes #37.”）
• 如果你的变更包括 HTML/CSS 中的差异，把之前和之后的屏幕截图包含进去。把图像拖放到你的拉取请求主体中。
• 测试你的变更！如果有现存的测试，对你的变更运行这些测试，如果需要，创建新的测试。无论测试存在与否，确保你的变更不会破坏现有的项目。
  • 尽你所能以项目的风格做贡献。这可能意味着相比你自己的仓库使用不同的缩进、分号或注释，但这样使维护者的合并、其他人的理解和将来的维护变得更简单。

如果你第一次使用拉取请求（ Pull Request ），查看“做一个拉取请求”，这是 @kentcdodds 创建的，可作为一个免费的演练资源。

第六部分：提交贡献之后会发生什么

你做到了！祝贺你成为一名开源贡献者。我们希望这是许多次中的第一次。

在你提交贡献之后，会发生以下情形之一：

你没有得到回应

但愿你在做贡献以前检查过项目的活跃迹象。然而，即使对一个活跃的项目来说，也有可能你的贡献得不到回应。

如果超过一星期了你还没有得到回应，有理由在同一个线索（thread）中礼貌地回复，请某人做审查。如果你知道审查你的贡献的合适的人的名字，你可以在线索中@-提到他们。

不要私下接触那个人；记住，公开的交流对开源项目来说至关重要

如果你做了一个礼貌的“碰撞”，还是没人回应，那可能永远也不会有人回应。这种滋味不好受，但不要因此气馁。每个人都经历过这种事！你没有得到回应可能有很多原因，包括可能不受你控制的个人境况。试着找到另一个项目或方式做贡献。如果有什么理由来解释为什么在其它团体成员投入这个项目此并作出回应前不要在贡献项目上投入太多时间的话，这就是很好的一个。

某人要求对你的贡献做改动

你常常会被要求对你的贡献做改动，无论是对你的想法范围的反馈，还是对你代码的改动。

当某人要求做改动时，要作出响应。他们花了时间审查你的贡献。开了一个拉取请求然后就走掉是不好的表现。如果你不知道怎样做改动，研究该问题，然后如果需要的话寻求帮助。

如果你不再有时间在该工单上工作（例如，如果会话已经进行了几个月，你的境况发生了变化），让维护者知晓，这样他们就不再期待一个回应。其他人可能乐于接手。

你的贡献没被接受

最后，你的贡献可能会，也可能不会被接受。但愿你没有在那里面做太多的工作。如果你不确定它为什么没被接受，要求维护者的反馈和说明是完全合理的。然而最终，这是他们的决定，你需要表示尊重。不要争论或怀有敌意。如果你意见不同，始终欢迎你 fork 并在你自己的版本上工作。

你的贡献被接受了

好极了！你成功地做了开源贡献！ 

第七部分：你做到了！

不管你刚刚完成了你的第一个开源贡献，或者你正在寻找新的贡献方式，我们希望你收到鼓舞并采取行动。即使你的贡献没有被接受，当维护者付出努力帮助你时，不要忘了说声谢谢。开源正是由像你一样的人造就的：选一个 Issue工单 、开一个拉取请求、评论，或逐一举手击掌。