如何写就完美 Pull Request

Question

译注：Github Blog 发表了一篇文章 How to write the perfect pull request，对书写 Pull Request 文案及相关话题给了些相当不错的建议，很适合开源协作，对使用 Github 的公司项目也有一些借鉴价值。祝愿大家都能写一手好文档，沟通愉快！

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

撰写 Pull Request

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

提供反馈

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

对反馈的回复

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

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

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