Github 开源项目贡献指南：如何给开源项目做贡献 （下）

本文是【Github开源项目贡献指南】系列的第一章的下篇，接上篇《Github 开源项目贡献指南-如何给开源项目做贡献 （上）》。

高效率的沟通

不管你是一个一次性的贡献者还是想要加入社区，和他人合作是你在参与开源项目过程中会培养的一项重要技能。

[作为一个新的贡献者]，我很快意识到如果我想关掉 issue 的话我得问一些问题。我浏览了一下代码架构，当我对项目有了基本的把握之后，我便询问我下一步该做什么。最后，当我了解了我所需要的所有细节之后，我能够解决那个 issue 了。 — @shubheksha, A Beginner’s Very Bumpy Journey Through The World of Open Source

在你打开一个 issue 或者 发起一个 pull request 或者在聊天室问一个问题之前，把下面这些要点记清楚以此来更好的表达你的想法。

给出上下文：帮助人们快速了解你提出的东西。如果你遇到了一个问题，解释你想做什么和怎样重重现该问题，如果你是在表达一个新的想法，解释一下为什么你觉得对项目来说这个想法是有用的（而不仅仅是对你而言）

正确示例: “当我做甲的时候，乙为什么不出现”

错误示例: “这个啥啥啥出问题了，麻烦修复它”

提前做好功课：无知是没问题的，但是告诉别人你已经尽力了。在寻求帮助之前，一定要先看看 README 文件，文档，issue（开着的关着的都要看），邮件列表，在网上也找一找。当你展示除了一种想要学习的态度的时候别人会很乐意帮助你。

正确示例: “我不确定怎么实现这个，我查看了帮助文档但是没有找到相关的内容”

错误示例: “我怎样做才能啥啥啥”

保持你的请求简短清晰：就像是发邮件一样，每一次贡献，不管是多么简单或者多么有帮助，都需要有人审查。很多项目提问的数量远远多于提供帮助的人。保持简洁，你会增加别人帮助你的概率。

正确示例: “我想写一个 API 使用教程”

错误示例: “当我有一天下高速加气的时候突然想到了关于我们正在做的事情的一个牛逼的点子，在我解释之前，让我先展示…”

保持所有交流都是公开的：就算私下联系项目的维护者是很诱人的，但是除非你要分享一些敏感信息（比如一个有关安全的 issue 或者是严重违反守则的行为），否则就不要这么做。当你让对话保持公开，更多人可以从你们的对话中学到更多。讨论本身也是一种对项目的贡献。

正确示例:(对于评论)”@-maintainer 你好！我们应该怎么处理这个 PR?”

错误示例: (对于邮件) “你好, 不好意思通过邮件打扰你，但是我想问一下你是否有时间审查一下我的PR”

可以问问题（但是一定要耐心！）： 从某种程度上来说，每个人都是某个项目的新人，即使是对于有经验的贡献者，当他们刚开始接触一个项目的时候也要费点力气。同样，即使是长时间维护项目的人也不是对项目的所有细节都了如指掌。如果你想让他们对你有耐心的话你首先得对他们有耐心。

正确示例: “麻烦你看一下这个错误。我采取了你的建议，这是输出。”

错误示例: “为什么你没解决我的问题，这不是你的项目吗？”

尊重社区的决定：你的想法可能和社区优先考虑的事情或者说看问题的视角不一样。他们可能会给你反馈或者拒绝你的想法。然而你应该和他们讨论然后寻求妥协，维护者会比你在决定方向上话费更多时间，如果你不同意他们的方向，你可以一直在你 fork 的仓库上工作，或者自己创建一个新项目。

正确示例: “你没能支持我想要的特性我很失望，但是就像你解释的那样，它只会对一部分的用户有用，我知道为什么。感谢你聆听我的建议”

错误示例: “为啥那么你不支持我的需求呢？这简直没法儿接受！”

总之，保持优雅的状态：开源项目是由来自全世界的协作者一起创造的。这意味着开源协作的背景是多语言，多文化，跨地理位置，跨时间区的。除此之外，用键盘敲出来的文字无法传达音调和情感。所以在交谈中要呈现出善意的一面。礼貌的在一个想法上表达不同看法，或者询问更多细节，表明自己的立场，都是可以的。努力让网络空间变得更美好。

收集背景信息

在你做任何事之前，快速检查一下你的想法还没在别处被讨论过。浏览项目的 README 文件，issues（开着的关闭的），邮件列表， Stack Overflow。你不需要花费数小时去浏览所有的信息，但是对一两个关键词的快速搜索也会大有帮助。

如果你在别的地方找不到你的问题，你就可以搞事情了。如果项目是在 Github 上的，以可以通过开 issue 或者发 pull request 和别人交流。

• Issues 就是发起一次交谈或者对话。
• Pull requests 验证某一种解决方案
• For lightweight communication，比如一个 clarifying or how-to question(待翻译)，在 Stack Overflow 上提问， IRC， Slack，或者其他的聊天频道，如果你所在项目有的话。

在你开 issue 或者 pull request 之前，查看项目的贡献文档（通常是一个叫 CONTRIBUTING 的文件，或者就在 README 里面），看看里面有没有你要的信息。举个例子，他们可能会让你遵照一个模板，或者要求你包含一个测试。

如果你想要做做一次比较大的贡献，先开一个 issue 问一下。最好是 watch 这个项目（在 Github 上，你可以点击 “watch” 这样你可以接受所有对话的通知），然后认识一下社区的成员，因为你的工作并不会被他们接受。

开一个 Issue

在以下的情况你就应该开一个 issue

• 报告一个你自己解决不了的错误
• 讨论一个高级别的话题或者想法（比如社区，vision（这个自己体会。。），政策
• 提出一个新功能或者其他的关于项目的想法

在 issue 中交流的小贴士：

• 如果你看到了一个开着的 issue ，而且你想解决他 在 issue 中评论让人们知道你在尝试解决他，这样别人就不会重复你的工作了。
• 如果一个 issue已经打开一段时间了，有可能这个 issue 别人已经在解决了，或者早就已经搞定了，所以在你开始动手之前在相应 issue 的评论里面问一下比较好。
• 如果你打开了一个 issue ，但是最后自己解决了， 在 issue 的评论里面告诉别人，然后关掉这个 issue 。甚至以文档的形式把你的成果展示出来也是对项目的一种贡献。

发一个 pull request

在以下的情况下你就可以发一个 PR 了。

• 提交一个小问题的修复（比如手误，挂掉的链接，或者明显的错误)
• 准备实现一个早就有人提过的需求，或者是解决在某个 issue 中讨论的问题

一个 pull request 不需要是现在已经搞定了的工作。通常最好是在这之前就发起开一个 pull request ，这样别人可以查看你的工作情况，或者对你现在的进度给予反馈。只要在标题行打上 WIP （正在进行中）的标签就行了。你可以稍后添加更多的信息。

如果项目是在 Github上的话，这里展示了如果提交了个 pull request：

• 复刻仓库 然后克隆到本地。通过把它添加到 remote 就把你的本地仓库和远程的“上游”仓库链接起来了。要经常从你的“上游仓库”拉取代码以此来保证同步从而当你提交你的 pull request 的时候，合并冲突就变得更容易了。（从这里查看更多教程
• 创建分支 用来编辑代码。
• 引用任何相关的 issue 或者在你的 PR 顺便附上相关信息（比如 “关掉 issue #37”）
• 包括修改之前和之后的截图 如果你的改动包含 HTML/CSS 文件。拖放图片到 pull request 的正文。
• 测试你的改动! 在你的改动上运行已经存在的测试，有必要的话创建新的测试。不管之前有没有测试，都要保证你的改动不会破坏项目已有的功能。
• 按照项目的风格改动 将你的能力发挥到最好。这意味着会使用和你自己仓库不一样的缩进，分好和注释风格。但是这会方便维护者合并，其他人在以后也好理解。

当你提交一次贡献的时候发生了什么

你做到了！恭喜成为一个开源贡献者。而我们希望这仅仅是开始！

当你提交你的 PR 之后，可能会发生以下几种情况。

你并没有得到回应

在你做贡献之前你还满怀希望的检查了标志项目活跃的要求。即使是一个活跃的项目，然后还是有可能你的贡献得不到回应。

如果你在一周之内都没有得到回应，你可以有礼貌的找别人帮你审查。如果你知道帮你审查贡献的合适人选的名字，你可以@他们。

不要私戳那个人；要时刻记住公开交流对开源项目来说是必要的。

如果这样还没人理你，那么就可能不会有人理你了，永远。这让人感到不爽，但是别因为这打击到你。每个人都可能会遇到这种情况！你没得到回复的原因有很多，包括你不能控制的私人原因。尝试着找另外一个项目做贡献。总之，在社区其他人还没参与和相应进来的时候你就不要话太多的事情在某个问题上面。

有人想改动你的PR

被要求改动你的贡献是很常见的，要么是对你的想法，要么是对你的代码。

当有人想改动你的PR的时候，务必回复！因为他们花时间审查了你的代码。你开个PR就跑路是不好的！如果你不知道怎么改，好好研究一下问题所在，如果需要的话可以寻求帮助

如果你没时间再搞某个 issue 了（举个例子，如果对话已经过去数月了，而且你的情况也有所改变），让维护者知道从而他们就不会等着你的反馈了。可能另外某个人会开心的接手你的工作。

你的贡献被拒绝了

到最后你的贡献不一定会被接受。如果你也没在这上面花太多功夫那是最好，如果你不确定为什么没有接受，你有完美的理由去询问维护者给你反馈和解释。不要争吵或者怀恨在心。如果你不认同它的看法你大可 fork 一份搞自己的版本。

你的贡献被接受了！

万岁！你已经完成了一个开源贡献！

你做到了！

不管你是已经完成了你的第一个开源贡献还是在寻找贡献的新途径，我们都希望你可以立即行动起来。即使你的贡献可能不会被接受，但是不要忘记当维护者花时间帮助你的时候要说声谢谢。开源世界就是由无数像你这样的人创造的：一个 issue ，pull request，评论和每一次的庆祝。