如何为开源项目提交贡献

你已经找到了你喜爱的项目，也已准备好贡献了，迫不及待、跃跃欲试了。好吧！以下就是带领你如何以正确的姿势作贡献。

有效沟通

无论你处于什么样的目的：仅仅是一次性的贡献，亦或是永久性的加入社区，都得和他人进行沟通和交往，这是你要在开源圈发展必须修炼的技能。

[作为一名新手,] 我很快的就意识到，我若是要关闭一条 issue 时，我不得不问更多的问题。我浏览了代码库，一旦我觉得有什么问题的时候，我就得需要更多的指点，瞧！ 在我得到所有的所需要的信息后，我就可以解决这个问题！

— @shubheksha , 一名菜鸟进入开源世界的坎坷之旅

在你开启一个 issue 或 PR 之前，或者是在聊天室问问题之前，请牢记下面所列出的几点建议，会让你的工作更加的高效。

给出上下文 以便于让其他人能够快速的理解。比方说你运行程序时遇到一个错误，要解释你是如何做的，并描述如何才能再现错误现象。又比方说你是提交一个新的想法，要解释你为什么这么想，对于项目有用处吗（不仅仅是只有你！）

???? “当我做 Y 的时候 X 不能工作”

???? “X 出问题! 请修复它。”

在进一步行动前，做好准备工作。 不知道没关系，但是要展现你尝试过、努力过。在寻求帮助之前，请确认阅读了项目的 README、文档、问题（开放的和关闭的）、邮件列表，并搜索了网络。当你表现出很强烈的求知欲的时候，人们是非常欣赏这点的，会很乐意地帮助你。

???? “我不确定 X 是如何实现的，我查阅了相关的帮助文档，然而毫无所获。”

???? “我该怎么做 X ?”

保持请求内容短小而直接。 正如发送一份邮件，每一次的贡献，无论是多么的简单，都是需要他人去查阅的。很多项目都是请求的人多，提供帮助的人少。相信我，保持简洁，你能得到他人帮助的机会会大大的增加。

???? “我很乐意写 API 的教程。”

???? ” 有一天我驾驶汽车行驶在高速公路上，在某个加油站加油的时候，突发奇想，我们应该这么做，不过在我进一步解释之前，我先和大家展示一下。。。”

让所有的沟通都是在公开场合下进行。 哪怕是很不起眼的小事，也不要去给维护者发私信，除非是你要分享一些敏感信息（诸如安全问题或严重的过失）。你若能够保持谈话是公开的，很多人可以在你们交换的意见中学习和受益。

???? (评论) “@维护者 你好！我们该如何处理这个 PR？”

???? (邮件) “你好，非常抱歉给发信，但是我实在很希望你能看一下我提交的 PR。”

大胆的提问（但是要谨慎！）。 每个人参与社区，开始的时候都是新手，哪怕是非常有经验的贡献者也一样，在刚进入一个新的项目的时候，也是新手。出于同样的原因,甚至长期维护人员并不总是熟悉一个项目的每一部分。给他们同样的耐心，你也会得到同样的回报。

???? “感谢查看了这个错误，我按照您的建议做了，这是输出结果。”

???? “你为什么不修复我的问题？这难道不是你的项目吗？”

尊重社区的决定。 你的想法可能会和社区的优先级、愿景等有差异，他们可能对于你的想法提供了反馈和最后决定的理由，这时你应该去积极的讨论，并寻求妥协的办法，维护者必须慎重的考虑你的想法。但是如果你实在是不能同意社区的做法，你可以坚持下去！继续维护自己的分支，或者另起炉灶。

???? “你不能支持我的用例，我很失望，但是你的解释仅仅是对一小部分用户起作用，我理解为什么。感谢你的耐心倾听。”

???? “你为什么不支持我的用例？这是不可接受的！”

最重要的是，保持优雅 开源社区有来自世界各地的协作者，所以跨语言、文化、地理位置和时区的情况下会丢失上下文语境。另外，书面交流使得传达语气或情绪变得更加困难。对话过程中善意地理解对方的意图、礼貌地反驳他人的想法，询问更多的上下文语境，或进一步澄清你的立场都是好事。我们要让互联网变得更加美好。

收集上下文

在正式开始之前，做一些快速的检查项，以确保没有人讨论过你的想法。看一遍项目的 README、问题（开放的和关闭的都算）、邮件列表、Stack Overflow。不需去花好几个小时去全部折腾一遍，但是使用几个关键的词汇来搜索一下是必要的。

如果你没有找到和你想法一样的内容，你就可以继续了。如果项目是在 GitHub 上的话，你可以通过开启一个 issue 或 PR：

• Issues 开启一次对话或讨论
• Pull requests 请求接受自己的解决方法
• 少量的沟通， 诸如澄清或”怎样做”的问题，尝试到 Stack Overflow、IRC、Slack 或其它聊天平台去问。

在你创建 issue 和 PR 之前，请检查项目的贡献者文档（文件名通常叫做 CONTRIBUTING，或者就直接包含在README中），找一些你需要的较具体的东西，例如，他们会要求你遵循某个模版，或者是要求你使用某个测试。

如果你做的是一个非常实际的贡献，在正式开启之前，先创建一个 issue。Watch 这个项目是很有帮助的（在 GitHub，点击 “Watch” ，所有的对话都会通知你），要让社区的成员们知道你要做的工作，免得你做了之后，再让他们知道，他们不同意，就浪费了。

你能够从单个的项目学习到 很多 ，只要你踊跃的去使用，在GitHub上密切观察项目，并阅读每一个 issue 和 PR。

— @gaearon 参与项目

创建 issue

你应该在遇到下列情况下，去创建一个 issue：

• 报告你自己无法解决的错误
• 讨论一个高级主题或想法(例如. 社区、远景、政策等)
• 期望实现某新的特性，或者其它项目的想法

在 issue 的沟通中几点实用的技巧:

• 如果你刚好看到一个开放的 issue，恰是你打算解决的， 添加评论，告诉他人你将负责这个。这样的话，可以避免他人重复劳动。
• 如果说某个 issue 已经开放很久了， 这可能是已经有人正在解决中，又或者是早已经解决过了，所以也请添加评论，在打算开启工作之前，最好是确认一下。
• 如果你创建了一个 issue，但是没多久自己解决了， 也要添加评论，让其他人知道，然后关闭该 issue。记录本身就是为社区的贡献。

创建 pull request

在下面的情形时，请你务必使用PR：

• 提交补丁 (例如，纠正拼写错误、损坏的链接、或者是其它较明显的错误）
• 开始一项别人请求的任务，或者是过去在 issue 中早就讨论过的

一个 PR 并不代表着工作已经完成。它通常是尽早的开启一个 PR，是为了其他人可以观看或者给作者反馈意见。只需要在子标题标记为”WIP”（正在进行中）。作者可以在后面添加很多评论。

如果说项目是托管在 GitHub 上的，以下是我们总结出的提交 PR 的建议：

• Fork 代码仓库 并克隆到本地，在本地的仓库配置”上游”为远端仓库。这样你可以在提交你的 PR 时保持和”上游”同步，会减少很多解决冲突的时间。(更多关于同步的说明，请参考这里 .)
• 创建一个分支 用于自己编辑。
• 参考任何相关的issue 或者在你的 PR 中支持文档(比如. “Closes #37.”)
• 包含之前和之后的快照 如果你的改动是包含了不同的 HTML/CSS。在你的 PR 中加入相应的图片。
• 测试你的改动！ 若测试用例存在的话，跑一遍，以覆盖你的更改，若没有的话，则创建相应的用例。无论测试是否存在，一定要确保你的改动不会破坏掉现有的项目。
• 和项目现有的风格保持一致 尽你最大的努力，这也就是意味着在使用缩进、分号、以及注释很可能和你自己的风格大相径庭，但是为了节省维护者的精力，以及未来他人更好的理解和维护，还请你容忍一下。

如果这是你第一次提交 PR。可以浏览 提交 PR 的文档，这是 @kentcdodds 专门为初次创建 PR 的人写的公开的资料。