如何写就完美 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” 的区别。