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