寫一個審查者能用的 PR 描述
目標:讓審查者在兩分鐘內決定要看什麼,並讓未來的讀者理解這個變更存在的原因。
蒐集
- 找到基礎分支,然後執行
git log --oneline <base>..HEAD和git diff --stat <base>...HEAD,接著閱讀 diff。 - 尋找原因:提交記錄或分支名稱中關聯的 issue 或票證編號、使用者的請求、diff 中加入的註解。如果原因不在這些地方,請詢問使用者;不要自行編造動機。
- 檢查測試了什麼:diff 中的測試檔案,以及使用者執行的指令。如果測試沒有被執行,請直接說出來。
- 尋找是否有
.github/pull_request_template.md或PULL_REQUEST_TEMPLATE。如果有,則填入該模板,而不是使用下方的結構。
結構
<Title: 祈使句,不超過 70 個字元,命名行為變更,而不是檔案>
## Why
<問題或請求,用 1 到 3 句話說明。如果有的話,附上 issue 連結。>
## What changed
- <按領域分組的行為層級項目,而不是檔案列表。>
## How to review
- 從 <檔案或領域> 開始;其餘部分皆以此為基礎。
- 風險較高的部分:<最容易出錯的部分,以及原因>。
- 特意未變更的內容:<審查者可能預期看到但找不到的項目>。
## Testing
- <執行的確切指令與結果。>
- <手動步驟與觀察結果。如果有,請寫「未測試:...」>
## Rollout / risk
<遷移、設定、功能旗標、相容性、如何回退。只有在屬實時才寫「無」。>
規則
- 描述 diff 實際做了什麼,而不是你希望它做了什麼。草擬後重新閱讀 diff,刪除任何它不支援的主張。
- 不要列出每一個檔案。要列出行為變更、新設定、新相依套件以及被刪除的程式碼。
- 不要有填充內容(如「此 PR 旨在...」)。除非該倉庫使用表情符號,否則不要使用表情符號。
- 螢幕截圖或輸出範例:說明何處會有幫助;絕對不要描述你沒有看到的螢幕截圖。
- 將標題和內容放在程式碼區塊中,以便複製。除非被要求,否則不要執行
gh pr create。