前言

在規模化開發環境中，缺乏規範的程式碼交付流程會導致嚴重的技術風險與維運成本。隨著 AI 輔助開發顯著提升了程式碼的產出速度，團隊必須建立一套穩定的 workflow 規範，以確保在快速的變更下，系統的品質與穩定性依然處於可控的狀態。

本篇將深入探討推薦的 Git Flow 架構、Conventional Commits 提交訊息模板，以及 PR（Pull Request）的命名與關聯規範。這套規範主要在為自動化 CI/CD workflow 提供明確的驅動邏輯，建立一個具備高可用性、可追溯性且安全穩定的軟體開發基礎。

現代化 Git Flow 架構與設計

下圖展示了程式碼在不同生命週期階段的分支路徑：

各分支的職責與存取控制

1. main (master) - 生產環境的絕對穩定版本

   • 職責：代表當前生產環境執行的程式碼。此分支上的每一筆提交都必須是經過完整驗證、具備高可用性的production發佈版本。隨時check-out使用都不會有任何問題。

   • 存取控制：嚴格禁止直接提交（Direct Commit）。所有變更必須透過 Pull Request (PR) 從 develop 或 hotfix 分支合併。

   • Workflow 觸發：合併至 main 將自動觸發正式生產環境的部署流程（CD），並同步產出版本標籤（Tag）。

2. develop - 整合與預發佈核心

   • 職責：所有新功能的整合中心，也是 Staging 環境的來源。

   • 存取控制：必須通過自動化門禁（Quality Gates）與程式碼審查（Code Review）後才可接受來自 feature 分支的合併。

   • Workflow 觸發：合併至 develop 將觸發測試環境的自動化建置與整合測試，確保變更不會對現有系統造成負面影響。

3. feature/ - 功能開發的隔離區

   • 職責：用於新功能的探索與開發。應秉持「小步快跑」的原則，頻繁進行本地提交與單元測試。

   • 命名規範：應包含相關的任務 ID，例如：feature/CICD-001-auth-module，以強化與需求系統的關聯性。

4. hotfix/ - 緊急修復的快速通道

   • 職責：專門用於修復生產環境中發現的關鍵漏洞或系統故障。

   • 核心規範（Hotfix Back-merge）：這是 Git Flow 中最重要的分支——Hotfix 在併入 main 分支後，必須強制合併回 develop 分支。這是為了防止Regression Issue的產生。若緊急修復未同步回開發主線，當下一次發佈週期到來時，剛修復的漏洞將會被未更新的 develop 程式碼覆蓋，造成嚴重的維護事故。

Git 提交訊息規範 (Conventional Commits)

為了讓 CI/CD 系統能自動解析變更歷史，並自動產出精確的發佈日誌（Release Notes），我們必須遵循 Conventional Commits 規範。

格式語法：

<type>[optional scope]: <description>

以下為type的常用選項：

• feat: 引入新功能（對應 Semantic Versioning 的 Minor 版本）。

• fix: 修復錯誤（對應 Semantic Versioning 的 Patch 版本）。

• docs: 僅修改文件。

• style: 不影響程式碼邏輯的格式調整（如：排版、標點符號）。

• refactor: 程式碼重構（既非修復 Bug 也非新增功能）。

• test: 增加或修正測試案例。

• chore: 基礎設施維護、相依性更新或輔助工具調整。

專業範例：

• feat(auth): 整合 GitHub OAuth2.0 認證流程

• fix(core): 修正支付模組中的併發競態條件（Race Condition）

Pull Request (PR) 命名與關聯規範

除了 Commit 訊息與分支名稱之外，PR 的標題與內容也是自動化流程與程式碼審查（Code Review）中非常關鍵的一環。

1. 標題命名原則

PR 標題建議直接沿用或對齊 Conventional Commits 的格式，並在最前面加上對應的任務 ID，方便 Reviewer 與自動化系統快速抓到核心重點：

• 格式建議：[<issue-id>] <type>(<scope>): <description>

• 範例：

  • [PROJ-53] feat(auth): 整合 GitHub OAuth2.0 認證流程

  • [PROJ-88] fix(core): 修正支付模組中的併發競態條件

2. PR 內容與自動化設定

在 PR 的描述欄位（Description）中，必須建立明確的上下文與自動化觸發指令：

• 關聯 Issue 宣告：使用平台關鍵字（如 Fixes, Closes, Resolves）或列出 ticket ID 來連結 Ticket 系統，讓系統在 PR 合併時自動更新任務狀態：

    Related to HLCT-53
    Fixes HLCT-53

• 變更摘要（Summary）：簡述這次 PR 解決了什麼問題、採取了什麼技術解法，縮短審查者的理解時間。

規範化管理的技術價值

• 環境風險隔離：確保開發中的不穩定因素或實驗性代碼不會意外洩漏至生產環境。

• 變更的可審計性：標準化的提交訊息讓團隊在面對資安審核或 Issue 調查時，能迅速定位變更的原因與影響範圍。

• 自動化驅動基礎：清晰的分支結構、語義化的提交紀錄與規範化的 PR 關聯，是實施自動化版本發佈（Semantic Release）與自動化部署的前提。

結語

標準化的 Git workflow、提交規範與 PR 管理是建立高頻率、低風險體系的先決條件。透過明確各分支的職責邊界與溝通語言，我們為後續的自動化流程建立了穩定的基礎。