Pull Requests 的魔法

1. 從合併到提議：為什麼需要 Pull Requests？

在上一堂我們學會了在本機合併 (merge) 分支。這在你單獨工作時很有效。但如果整個團隊都在做這個專案呢？如果每個人都直接把自己的改動合併到主要分支 main，很快就會變成混亂：有人可能會不小心新增有 bug 的程式碼、破壞 build，或刪掉同事重要的工作。

為了避免這種情況，團隊開發採用不同的做法。不是立刻合併改動，而是創建一個合併提議。這個提議叫做 Pull Request（縮寫 PR），在某些平台上也叫 Merge Request。

Pull Request — 這是一個正式的請求：「請把（pull）我的改動從我的分支拿走並合併（merge）到主要分支」。但它不僅僅是請求，而是一個討論、檢查和改良程式碼的平台，讓改動在進入 main 前變得更好。

2. 有關 Pull Request 的標準工作流程

我們一步步來看，新增功能時典型的工作流程是怎樣的。

在創建新分支以處理任務前，先確保你已經把所有已完成的提交 (push) 發送出去，並且把主分支 main 更新了（Update Project）。

否則你本地在 main 上遺漏的提交可能會意外地出現在新的 Pull Request 裡，給同事造成混淆。

步驟 1. 為新任務創建分支。

一如既往，任何新的工作都從建立一個獨立分支開始。假設我們要在專案加入給貢獻者的規範檔案，我們可以創建分支 feature/add-contribution-guide。

步驟 2. 做改動並把你的分支推到 GitHub。

在新分支中創建檔案 CONTRIBUTING.md（建立後按 Add），然後寫下一些給其他開發者的留言。接着用清楚的訊息做 Commit and Push，例如：docs: Add contribution guide。

這一步很關鍵！ Pull Request 是基於已存在於遠端的分支建立的。所以在創建 PR 前，務必把你的新分支 push 到 GitHub。

3. 在 IntelliJ IDEA 中創建 Pull Request

現在你的分支已經在 GitHub 上，可以創建 Pull Request 了。

步驟 1. 打開 Pull Requests 分頁。

IDE 左側有個分頁叫 Pull Requests。打開它，按 + 標誌來創建新的 PR。

步驟 2. 填寫 PR 的資料。

IDE 會自動為你打開一個方便的建立 Pull Request 的介面。你的任務是把它填好。下面是主要欄位說明：

1. 標題：IDE 常常會把分支名稱放進來，但這是個壞習慣。標題應該簡短、清楚並反映改動的要點，像是一個好的 commit 訊息。
2. 描述：在這裡解釋你做了什麼和為什麼要做。
3. 審查者（Reviewers）：在這裡選擇一位或多位同事來檢查你的程式碼。在教學專案可以跳過，但真實工作中這是必要步驟。
4. 執行者（Assignees）：通常會把自己放在這裡，表示你是作者並且主要負責在審查後做修改。

當所有欄位填好後，就按 Create Pull Request。

4. Code-review：檢查與討論

PR 建立後進入最重要的階段 — 代碼審查 (code review)。你的同事可以打開你的 PR，查看所有改動並留下評論。

你可以直接在 IDE 的 Pull Requests 分頁看到所有討論。如果有人留了意見，你會收到通知。

被要求修改時該怎麼做？

很簡單！不需要重新創建新的 PR。只要在同一分支做需要的修改，做新的 commit 並 push 上去。GitHub 上的 Pull Request 會自動更新，包含你新的提交。

5. 結束工作：合併與刪除分支

當所有意見都處理完並且團隊同意你的改動，Pull Request 就可以合併了。通常由資深開發者來做，或是如果你有權限也可以自己合併。

步驟 1. Merge

合併通常在 GitHub 網站上進行。在你的 PR 下會有一個大大的綠色按鈕 Merge pull request。按下去後，你的程式碼就會成為主要分支 main 的一部分。

步驟 2. 刪除分支。

合併後你的 feature 分支通常不再需要，應該刪除以免污染 repo。GitHub 會提示你，並顯示 Delete branch 按鈕。

別忘了在自己的 IDE 也刪除本地分支，保持整潔。可以在分支管理選單中完成這個操作。

6. 三個 commit 規則

好的一次 commit 不只是一個好的訊息，也要有合適的內容。為了讓變更歷史清晰、有用且專業，請遵守三個簡單規則。

規則 1：按標準寫清楚的訊息

你的 commits 是你給團隊和未來自己的訊息。充滿「fix」或「update」的歷史沒什麼用。最流行的標準叫做 Conventional Commits，它建議的結構是：

<type>: <short description>

type 是一個短字，用來描述改動類別：

• feat: (feature) — 新功能。
• fix: — 修 bug。
• docs: — 文件更動。
• style: — 格式修正，不影響程式邏輯。
• refactor: — 重構，既不新增功能也不修 bug。
• test: — 新增或修正測試。
• chore: — 例行任務，和程式碼功能無關（更新依賴、build 設定）。

範例：

• 糟： fixed bug
• 好： fix: Correct user login validation

• 糟： readme
• 好： docs: Update installation instructions

規則 2：一個 commit 一個邏輯改動（原子性）

不要把修 bug、新功能和重構塞到同一個 commit 裡。這種 commit 很難審查，若要回滾也幾乎不可能不帶來副作用。

每個 commit 應該只解決一個具體問題。

• 糟： 一個 commit，訊息是 "Update user page"，裡面同時新增頭像欄位、修正使用者名稱驗證 bug，並改變按鈕顏色。
• 好： 三個不同的 commit:
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

小且聚焦的 commits 更容易理解與管理。

規則 3：commit 不應該讓專案崩潰

每個合併到主分支的 commit 都應該讓專案保持可運作狀態。提交前至少要確定程式能編譯。但如何保證你沒意外破壞系統其他部分？只靠人工檢查風險太大。

這時候就需要自動化。本課程不會教你怎麼完整配置自動化，但你應該知道真實專案是怎麼做的。現代團隊使用持續整合（Continuous Integration, CI）系統，例如 GitHub Actions。

它怎麼運作？

你寫程式和對應的測試，然後在 GitHub 上設定一個 workflow。只要你把改動 push 到 Pull Request，就會發生以下事情：

1. GitHub Actions 偵測到事件並啟動你的 workflow。
2. 它會自動「build」專案並 執行所有測試。
3. 如果所有測試都通過，你的 commit 在 GitHub 上會出現一個 綠色勾勾，這對團隊來說是改動安全的信號。
4. 如果至少有一個測試失敗，你會看到 紅色叉叉。這種情況下嚴禁把 PR 合併到主要分支。

            graph LR
            subgraph GitHub
            A[開發者] -- "push" --> B(Repository)
            B -- "事件: push" --> C{GitHub Actions}
            end

            subgraph Workflow
            C -- "啟動" --> D[Run_Tests]
            D --> E[成功]
            D --> F[失敗]
            end

            subgraph Notifications
            F --> G((Email))
            G --> H[開發者]
            G --> I[團隊]
            end

            style F fill:#f99,stroke:#333,stroke-width:2px
            style G fill:#ccf,stroke:#333,stroke-width:2px
        

可以設定通知。如果測試失敗，GitHub Actions 可以發郵件給你或整個團隊。這種做法會培養一種文化：測試不是走形式，而是開發中不可或缺的一部分，每個人都要為自己程式碼的品質負責。