Pull Request 书写指南

基于 Github Flow 进行协做时，如何基于完整、清晰的 Pull Request 进行沟通是其中关键一环。工具检查是最有力的保障，但代码以外的文字部分只能靠约定，本文就是对 Pull Request 文字书写部分的规范。简单来讲，五条约定：

TL;DR

1. 一个 PR 只围绕一件事情

2. 避免超大的 PR

3. PR 标题——概述这次 Pull Request 的目标

4. PR 说明——面向将来的 Reviewer

5. 详述须要哪些反馈（若是有的话）

这些约定的目标是增长开发过程的透明度，好处（包括但不只限于）：

• 利于 Reviewer 快速准确地完成 review

• 新近成员能更快理解历史代码和渊源

• 追查 Bug 时的线索更充分而无关干扰更少

立下约定很简单，真正的难点在于执行。因此这些规范条款尽可能不作太多严格的约束，以便执行的时候可以严格操做。若是你以为某一项在团队中很难推行开来，就撤掉它，不要写在章法里却没法执行。

下面是对这五条约定的详细说明：

撰写 Pull Request

1. 一个 PR 只围绕一件事情

   • 若是确有必要将几件事情（例如修改特别小、相互之间有依赖等）一块儿提交 PR，则须要列明具体每一件事情，确保 __PR 说明涵盖了全部修改内容__。

   • __大片的代码格式整理__要做独立提交（Commit），不要和__代码修改__混在一块儿，以便 Reviewer 能轻松查看干净的代码修改 diff。

2. 避免超大的 PR

   • 超过 1000 行修改行数的 PR 须要考虑是否能拆分为多个子任务分别提 PR（合理的程序结构设计也应该是解耦的）。

   • 若是 PR 包含的提交数量过多，一般是开发过程掺杂了“尝试—修问题—换个方法再来”这样的重构反复。此种状况最好抛弃这些过程提交，新开分支逐个应用有意义的修改，而后提 PR。

3. PR 标题——概述这次 Pull Request 的目标

   • 例如：尝试用 XXX 方法实现……、优化……、修复在 XX 状态下对 XX 的异常处理。

4. PR 说明——面向将来的 Reviewer

   • 记住公司里任何人，任什么时候候都有可能来阅读这个 Pull Request，因此内容和语气都须要面向将来可能的 Reviewer，不要假定对方已经熟悉这些事情的来龙去脉。

   • 酌情提供关于这些工做原由的说明，记得包含相关连接。例如跟特殊业务相关的地方，须要添加相关业务文档连接；处理了很是奇异的 Bug，就有必要附上相关线索、资料连接。

5. 详述须要哪些反馈（若是有的话）

   • 如：@某人过目一下代码/讨论某项技术实现/对设计的意见等等。

   • 明确你什么时候须要反馈。若是这个 PR 尚未完成（仍有一些代码修改待推送）则需醒目注明，常见作法是给标题加上[WIP]（施工中）的前缀。

附：提供反馈

• 首先要了解下此 PR 的前情提要。

• 若是你有强烈的反对意见，多花几分钟审视下本身的意见再提。Think Twice。

附：对反馈的回复

• 尽可能回复全部评论，尊重评论者对 PR 的关心。

• 连接到相关的后续提交。（“好建议！a1da2324ca 已搞定 :D”）

• 若是疑惑和争论持续扩大，尝试面对面作充分沟通。以后把线下沟通的内容汇总回复（便于其余人跟踪进展或者在将来了解详情）。

附：对本文的反馈

本文有一个Github 仓库，偶有文案调整。也欢迎提出来你在实践中遇到的问题，一块儿改进这份文档 :D