PR 摘要工作流

PR 摘要不是給作者看的，是給 reviewer、未來排障的人和釋出負責人看的。Copilot 可以生成第一版，但作者必須把業務背景、風險和驗證補全——把 Copilot 摘要原樣提交，等於把"使用者影響 / 風險 / 測試 / 回復"四件事甩給下一個看 PR 的人。

1. 摘要結構

一份能用的 PR 摘要至少包含 5 塊：

## What changed
- ...

## Why
- ...

## Risk
- ...

## Tests
- ...

## Rollback
- ...

如果團隊只允許短摘要，也至少保留 What changed、Risk、Tests。沒有風險和測試說明的摘要，只是 changelog。

2. 工作流

flowchart TD
    Diff["PR diff"] --> Blank["保持 description 空白"]
    Blank --> Generate["Copilot Summary"]
    Generate --> Author["作者人工補充"]
    Author --> Verify{"對照 issue / diff / tests"}
    Verify -->|缺背景| Author
    Verify -->|缺風險| Author
    Verify -->|透過| Publish["Create PR / Update comment"]
    Publish --> Reviewer["Reviewer 快速進入上下文"]

    style Generate fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Author fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Publish fill:#dcfce7,stroke:#16a34a,stroke-width:2px

3. 生成前準備

先確認 PR 本身已經有基本衛生：

• 分支只包含本次任務相關提交。
• PR 標題說明具體行為，不寫“fix”或“update”。
• diff 沒有混入格式化、除錯日誌、臨時檔案。
• 測試命令已經跑過，失敗項有解釋。
• issue、設計說明或截圖已經準備好。

Copilot summary 是壓縮上下文，不是清理混亂 diff 的工具。diff 越雜，摘要越容易泛化。

4. 生成後人工補齊

Copilot 生成後，作者逐項補齊：

1. What changed：按使用者可感知行為、介面、資料、UI 或配置說，不按檔案流水賬說。
2. Why：連結 issue 或說明業務原因，避免 reviewer 重新猜需求。
3. Risk：寫可能受影響的路徑、相容性、資料遷移、許可權、效能和斷點。
4. Tests：寫真實執行過的命令、手動驗證和沒有覆蓋的項。
5. Rollback：說明能否 revert、是否涉及資料回復、是否需要配置開關。

示例補充 prompt：

把这份 PR 摘要改成
reviewer 可用版本。

要求：
- 保留 Copilot 生成的事实。
- 不要编造未发生的测试。
- 按 5 段结构重排。
- 覆盖断点、权限和回滚。
- 测试只写我提供过的命令。

5. Reviewer 視角檢查

提交前按 reviewer 視角讀一遍：

• 我能否 30 秒內知道這次改了什麼？
• 我能否知道應該重點 review 哪些風險？
• 我能否找到測試證據？
• 如果上線出問題，摘要能否幫助快速 revert 或定位？
• 摘要有沒有把 Copilot 猜測當事實？

本章自檢

1. 是否從空白描述生成，或在 comment field 裡生成草稿？
2. 是否人工補齊背景、風險、測試和回復？
3. 是否對照 diff、issue 和測試結果核驗事實？
4. 是否刪除了“看起來合理但沒有證據”的句子？
5. 是否讓 reviewer 知道重點看哪裡？

透過標準：摘要能縮短 reviewer 進入上下文的時間，同時不犧牲事實準確性。

官方來源

• Creating a pull request summary with GitHub Copilot —— GitHub 官方 PR summary 使用說明。
• GitHub Copilot documentation —— GitHub 官方 Copilot 文件總入口。

接下來去哪