Pull-Request
一句話定義
「請求把我的 branch 合併到專案的主分支」——託管平台（GitHub / GitLab / Bitbucket / Gitea）在 Git 之上加的 code review + 合併介面層；不是 Git 原生功能，是社交化協作機制。
核心要點
命名邏輯
PR 的核心隱喻：主分支屬於專案 / feature branch 屬於個人——即使同一人擁有兩者，在這兩個分支上他扮演不同角色。
「Pull Request 的意思是：request 這個項目的主人把我這個新的分支的改變給 pull 到這個項目裡去——所以叫 pull request。」（2026-05-01-十分鐘GitHub工作流）
GitLab 用 Merge Request（MR）——同一機制不同稱呼，強調的是「合併」動作而非「拉取」隱喻。Bitbucket / Gitea / Codeberg 都沿用 PR / MR 名稱。
PR 在工作流中的位置
對位 GitHub工作流 七步 happy path：
clone → checkout -b → diff → add → commit → push → 【PR ←──── 你在這裡】── 合併
PR 是 push 之後、合併進 main 之前的那一步——接收 review、討論、調整、最終合併的介面。
合併策略選擇（GitHub 預設三選一）
| 策略 | feature branch 多 commit 進 main 後變成 | 適用情境 |
|---|---|---|
| Squash and Merge（GitHub工作流 預設） | 一個 clean commit | feature branch 開發過程亂、main 要乾淨；目標：main 每個 commit 都是正常工作的 |
| Create a Merge Commit | 全部 commit 保留 + 一個 merge commit | 想保留 feature 開發過程歷史 |
| Rebase and Merge | 全部 commit 保留為線性追加 | feature branch 已是乾淨的 commit-by-commit 故事 |
為何 squash 是預設：feature branch 常含 fix typo / 格式調整 / debug 嘗試等雜訊 commit；這些不該污染 main 的 history。Squash 把這些收斂成單一作者外觀——對位 程式碼風格指南 Golden Rule「每一行程式都看起來像同一個人寫的」在 commit history 層的具體執行。
PR 是 code review 的機構化介面
PR 不只是合併按鈕，更是結構化的 review 場域：
- diff 視圖 — 自動以檔案 / 行為單位呈現改動
- 行內評論 — 在具體哪一行哪個變數討論
- change request — 阻擋合併直到問題解決
- CI 狀態 — 測試 / lint / type check 結果直接顯示，紅燈擋合併
- 討論記錄 — 為什麼這樣寫的決策歷史被永久保存
對位 程式碼風格指南「PR 是 style guide 的最後一道把關」：再短的 style guide 也需要 review 時人 / hook 確認。
2026-05-06-Google-Code-Review 補上 PR 介面背後的判準：reviewer 不是在 diff 上追求完美，而是在 design / functionality / complexity / tests / naming / comments / style / docs / context 等面向判斷這個 PR 是否讓 codebase health 整體變好。
Force Push 與 PR 互動
git rebase main 後本地 commit hash 改變 → 必須 git push origin myfeature -f。GitHub PR 介面會自動更新為新的 commits 列表（同一 PR 號碼），但既有的 review 評論可能變成「outdated」狀態——因為它們指向舊 hash 的具體行。
開源專案的 PR 文化
PR 也是開源協作的標準介面：
- 任何 GitHub 用戶都可 fork 公開倉庫 → 改 → 開 PR 給原作者
- 原作者透過 PR 討論決定接 / 不接 / 怎麼改
CONTRIBUTING.md/ Issue Templates / DCO 簽署等都是這個介面的禮儀層
這與「個人 / 公司專案的 PR」是同一機制不同尺度——個人專案 PR 主要是自我紀律與 CI 把關 / 開源專案 PR 多了外部貢獻者把關這層。
與其他概念的關係
- Code-Review — PR 是 code review 的機構化介面；Code-Review 補的是 approval 標準、審查面向、comment 寫法與衝突處理。
- GitHub工作流 — PR 是這套工作流的第七步 + 合併環節；本概念的最完整應用上下文。
- Git — PR 不是 Git 原生功能；是託管平台層在 Git 之上加的社交化機制。底層動作仍是 git merge / rebase。
- GitHub — GitHub 發明 / 推廣 PR 機制；現已成跨平台事實標準（GitLab MR / Bitbucket PR / Gitea PR / Codeberg PR 都源自此設計）。
- 程式碼風格指南 — PR 是 style guide 的最後一道把關；squash-merge 對位 Golden Rule「每一行程式都看起來像同一個人寫的」在 commit history 層的具體執行。
- AI輔助開發 — AI 自動 PR review 是 Claude-Code 教程列出的代表性企業級用例；PR 介面是 AI agent 與人類團隊的標準交接點。
- Claude-Code — Claude Code 教程明確列「自動 PR review」為企業級用例；GitHub MCP server 讓 Claude Code 能讀 PR / 寫 review / 開 PR。
相關來源
- 2026-05-01-十分鐘GitHub工作流 — vault 中第一份系統處理 PR 的來源；含命名邏輯（主分支 vs feature branch 角色分離）+ Squash-merge 預設選擇 + 合併後刪除遠端 branch + 同步本地 main 完整流程
- 2026-05-06-Google-Code-Review — 補入 PR 作為 code review 場域時的判準：better not perfect / Nit / every line / context / response time / pushback
備註
建頁理由：PR 是 vault 中 AI輔助開發 多次提到但未深入的概念（Claude-Code 教程明確以「自動 PR review」為企業級用例）；累積到第一份完整流程來源時建獨立概念頁。理由：(1) 不是 Git 原生機制，須與 Git 分開；(2) 是跨平台事實標準（不只 GitHub），併入 GitHub entity 會限縮視角；(3) 累積方向多元（AI agent 自動 review、stacked PRs、CI 整合、開源 PR 文化等）。
未來累積方向：(a) AI agent 自動 PR 流程（Claude Code / Cursor / Aider 的具體實踐）；(b) Stacked PRs / Graphite / Spr 等進階管理工具；(c) Conventional Commits / semantic-release 等規範與 PR 的整合；(d) 開源專案的 PR 禮儀（CONTRIBUTING / DCO / signed commits）；(e) Branch protection rules / required reviews / CODEOWNERS 等治理層機制；(f) 不同合併策略的具體權衡案例累積。