Pull Request 的魔法

1. 從合併到提案：為什麼需要 Pull Request？

在上一堂課我們學會在本機電腦合併（merge）分支。當你單獨工作時這非常有效。但如果是整個團隊在同一個專案上工作呢？如果每個人都把自己的變更直接合併到主分支 main，很快就會一團亂：有人可能不小心加入有錯的程式碼、弄壞建置，或刪掉同事的重要成果。

為了避免這種情況，團隊開發採用另一種做法。不是立刻合併變更，而是先建立合併提案。這個提案稱為 Pull Request（簡稱 PR），或在某些平台上稱為 Merge Request。

Pull Request 是一種正式請求：「請取回（pull）我在分支上的變更，並將它們合併（merge）到主分支」。但它不只是請求，而是在變更進入 main 之前，用於討論、檢查與改進程式碼的完整平台。

2. 使用 Pull Request 的標準工作流程

讓我們一步一步看看，建立新功能時的典型工作流程。

在為新任務建立分支之前，請先確認你已推送所有完成的提交（push），並更新（Update Project）主分支 main。

否則，你在 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 常會在這裡自動帶入分支名稱，但這不是好做法。標題應簡短、清楚，並能反映變更的重點，就像一則好的提交訊息。
2. 描述：在這裡說明你做了什麼以及為什麼要這麼做。
3. 審查者：在這裡選擇一位或多位需要審查你程式碼的同事。在教學專案中可以略過這一步，但在真實工作中是必要的。
4. 受指派者：通常在這裡填寫你自己。這表示你是作者，也是此任務的主要負責人，並負責在審查後進行修改。

當所有欄位都填寫完成後，直接按下 Create Pull Request。

4. 程式碼審查：檢查與討論

建立 PR 後，最重要的階段開始了——程式碼審查（code review）。你的同事可以打開 PR，查看所有變更並留下評論。

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

如果被要求修改怎麼辦？

非常簡單！不需要建立新的 PR。只要在同一個分支修改程式碼、建立新的提交，然後推送（push）。GitHub 上的 Pull Request 會自動更新，加入你的新提交。

5. 收尾：合併並刪除分支

當所有意見都已修正且團隊核可你的變更，就可以合併 Pull Request。通常這由資深開發者執行；如果你有權限，也可以自行完成。

步驟 1. Merge

合併多半在 GitHub 網站上進行。在你的 PR 下方會出現一個大型綠色按鈕 Merge pull request。按下後，你的程式碼將成為主分支 main 的一部分。

步驟 2. 刪除分支。

合併之後，你的 `feature` 分支已不再需要，應該刪除以免弄亂儲存庫。GitHub 會主動提示，顯示 Delete branch 按鈕。

別忘了也在你的 IDE 中刪除本機的分支副本，以保持整潔。可以透過同一個分支管理選單完成。

6. 三條提交規則

好的提交（commit）不僅需要正確的訊息，還需要恰當的內容。為了讓你的變更歷史乾淨、有用且專業，請遵守三個簡單規則。

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

你的提交就是你發給團隊與未來自己的訊息。充滿「fix」或「update」的歷史完全沒有幫助。最流行的標準叫做 Conventional Commits。它建議使用以下結構：

<type>: <short description>

類型——用一個短字描述你的變更類別：

• feat：（feature）—— 用於新增功能。
• fix：—— 用於修復錯誤。
• docs：—— 用於文件變更。
• style：—— 用於格式調整，且不影響程式邏輯。
• refactor：—— 用於不新增功能、也不修錯的重構變更。
• test：—— 用於新增或修正測試。
• chore：—— 用於與程式碼無直接關係的例行工作（更新相依、建置設定）。

範例：

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

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

規則 2：一個提交——一個邏輯變更（原子性）

不要嘗試把修 bug、新增功能與舊程式碼的重構全塞進同一個提交。這樣的提交非常難以審查，且幾乎不可能在出問題時無痛回滾。

每個提交都應只解決一個明確的任務。

• 不好： 一個訊息為「Update user page」的提交，同時加入使用者大頭貼欄位、修正名稱驗證錯誤，還改了按鈕顏色。
• 好： 三個不同的提交：
  1. feat: Add avatar upload to user profile
  2. fix: Correct username validation logic
  3. style: Update button colors on user page

小而聚焦的提交更容易理解與管理。

規則 3：提交不應讓專案無法運作

主分支中的每個提交都應讓專案保持可運作。在建立提交之前，你至少要確保程式可以編譯。但要如何確保你沒有不小心弄壞系統的其他部分？只靠手動檢查風險很高。

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

這怎麼運作？

你撰寫程式碼與測試，然後在 GitHub 上設定一個工作流程（workflow）。此後，只要你向 Pull Request 推送（push），就會發生如下流程：

1. GitHub Actions 偵測到此事件並觸發你的工作流程。
2. 它會自動「建置」專案並且執行所有測試。
3. 如果所有測試都通過，你在 GitHub 的提交旁會看到一個綠色勾號。這向整個團隊表明你的變更是安全的。
4. 如果有任一測試失敗，你會看到紅色叉號。嚴禁將這樣的 PR 合併到主分支。

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

            subgraph Workflow
            C -- "觸發" --> D[執行_測試]
            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 可以發信給你或整個團隊。這種作法能建立一種文化：測試不只是形式，而是開發不可或缺的一部分，每個人都必須為自己程式碼的品質負責。