如何写就完美 Pull Request

译注：Github Blog 发表了一篇文章 How to write the perfect pull request，对书写 Pull Request 文案给了些相当不错的建议。祝愿大家都能写一手好文档，沟通愉快！

随着公司规模增长，人和项目都在变化。在 Github，我们的经验是经常提醒自己沟通的目标非常有助于保持沟通的高效率，为此我们最近提出了一份关于提交 Pull Request 的指南，帮助大家在使用 Pull Request 时能更好地协作。

撰写 Pull Request

• 要涵盖此次 Pull Request 的目标，例如：
  尝试用 XXX 方法实现……
优化……
修复在 XX 状态下对 XX 的异常处理
• 可以提供一份关于这些工作起因的说明（包含上相关链接）。不要假定对方已经熟悉这些事情的前因后果。
• 记住公司里任何人都有可能来阅读这个 Pull Request，所以内容和语气都需要面向那些未参与工作内容的人，现在和未来的。
• 如果有的话，请详述你需要的反馈，如：快速过目一下代码/讨论某项技术实现/对设计的意见等等。
• 明确你何时需要反馈。如果这个 PR 还在没有完成，就需要这么注明一下。给标题加上[WIP]（施工中）的前缀也是个简便快捷的方法。
• @艾特 需要特别指明加入讨论的人，并说明原因（“/cc @hax 麻烦来看下这个逻辑对么？”）。
• 同样的方法也可以艾特团队（“/cc @baixing/sa 这么做没安全问题吧？”）。

提供反馈

• 首先要了解下此 PR 的前情提要。
• 如果你有强烈的反对意见，多花几分钟审视下自己的意见再做反馈。Think Twice。
• 询问，不要指点。（“为什么你要……”而非“不要……”）
• 解释你提出修改意见的原因。（和代码规范不符？个人喜好？）
• 提供简化或改进代码的方法。
• 在提到别人的工作成果时避免使用贬义词（愚蠢什么的）。
• 谦逊。（“我不很确定，不过可以试试……”）
• 不要夸张。（“任何时候绝对……”）
• 评论旨在提高专业技能、产品质量，达成团队共识。
• 在线交流时要当心负面歧义（如果文字内容中性，我们倾向认为语气偏负面），尽量使用积极的语气而非中性的。
• 善用表情符号美化语气。（感受一下 “看起来不错。” 和 “看起来不错 ^O^”）[译注1]

对反馈的回复

• 考虑以感激作为开场白，尤其是当反馈混杂了各种意见的时候。
• 如有不明白的地方，请求进一步澄清。（“我不大明白，你能再解释一下么？”）
• 提供澄清。解释对方询问的实现方案是如何决策的。
• 尽量回复所有评论。
• 链接到相关的后续提交。（“好建议！a1da2324ca 已搞定 :D”）
• 如果疑惑和争论持续扩大，首先审视自己在前面的讨论中是否表达良好，尝试面对面做充分沟通，之后把线下沟通的内容汇总回复（便于其他人跟踪进展或未来了解详情）。

这份指南部分受到了 ThoughtBot 的 Code Review 指南的启发。

这份指南很适合我们的工作方式，以及我们想要建立的协作文化，希望对你也有帮助。

沟通愉快！

[译注1]: Github Blog 原文使用了 emoji 语气无比欢快可爱，sf.com 暂不支持，请至原文感受那两句 “looks good” 的区别。