# Git Branching（分支策略） 本文件定義本專案的分支層級、本地與遠端的一致性、版本分支的誕生、合併流向與分支刪除機制。所有功能開發與版本演進一律遵循。 ## 分支層級 ```text 功能分支（feature/） ↓ 先合併 版本分支（x.y.z.n，例如 2.0.0.2） ↓ 再合併 整合版-dev（主分支） ``` - **功能分支**：一個功能一個分支，可依需要獨立開；日常開發與驗證都在此進行。 - **版本分支**：承接該版本的全部功能分支，是版本驗收與回歸的基準。 - **整合版-dev**：主分支，只接受來自版本分支的合併。 ## 本地與遠端的一致性 - **主分支（`整合版-dev`）與版本分支（`x.y.z.n`）必須與遠端同名分支保持一致**：本地不得長期領先或落後；收斂與推送要在同一輪完成。 - **其餘本地分支預設不推遠端**：功能分支刻意留在本地，遠端不建立對應引用，遠端倉庫只保留主分支與版本分支，提交歷史因此保持乾淨。 - 所以「功能分支不在遠端」是策略，不是缺失；但功能分支的內容必須經由版本分支流向主分支，才會落到遠端。 ## 版本分支的誕生與編號 - 新版本分支從**最新的已驗收版本分支**切出（例如 `2.0.0.5` 自 `origin/2.0.0.4`），不從主分支或更舊的版本切。 - 編號遞增，跳號不補（`2.0.0.3` 缺號是歷史事實，不回填）。 - **建立時必須明確 upstream**：`git branch <新版本> origin/<舊版本>` 會讓新分支自動追蹤舊版本分支，直接推送就會把新版本內容推進舊版本分支。建立後立即改成追蹤遠端同名分支；同名遠端分支尚未存在時，先 `--unset-upstream`，待首推送後再設定。 - 版本分支**統一保留**，不刪除，作為歷史演進留檔。 ## 功能分支的起點與位置 - 功能分支**從目標版本分支切出**，不要從其他版本線或主分支切：切錯起點會把別條版本線的內容一起帶進目標版本（例：從 `2.0.0.2` 線切，併入 `2.0.0.5` 時連帶把 `docs/permissions-inventory.md` 帶上）。 - 功能分支**留在本地、不推遠端**（見「本地與遠端的一致性」）。 - 分支命名 `feature/`；需長期保留者加 `keep/` 前綴。 ## 合併流向 1. 新功能開發從**目標版本分支**獨立開功能分支。 2. 功能分支**先合併入版本分支**，**再由版本分支合併入整合版-dev**。 3. 功能分支不得直接合併進整合版-dev；版本分支不得跳過驗收直接改動。 4. **落到版本分支一律用 merge，不得用 cherry-pick**：cherry-pick 會為同一份改動造出第二個 SHA（本專案已發生：`0076dc0b` 與 `9748463e` 同一份改動），之後的合併會讓兩個 SHA 同時進入歷史，形成疊影與後續撞點。 5. 合併前先算兩側改動的交集做衝突預檢；合併後對自動合併檔**逐側比對**，確認雙方業務改動都保留（禁止盲目 `--ours`／`--theirs`）。 ### 例外（可直接進主分支） - 極小改動（例如文案錯字、單行修正）。 - 上線後需要調整的參數配置（例如環境位址、開關預設值）。 例外情況才可直接進整合版-dev；其餘一律走「功能分支 → 版本分支 → 整合版-dev」。 ## 驗收與收斂 - 版本分支是該版本的驗收基準；**驗收通過後才把版本分支合併進 `整合版-dev`**。 - 尚未驗收的版本分支不得進主分支；主分支落後於版本分支，即視為待辦的收斂項。 ## 推送版本分支的更新日誌（公告用） 推送遠端版本分支（`x.y.z.n`）前，必須先寫好本次的更新日誌，內容用於對外公告；日誌未寫不得推送。 - 落點：`.ai/history/release-notes.md`，每次推送版本分支追加一節，不覆寫既有節次。 - 時機：推送**前**完成，內容與該次推送的實際提交一致；推送後補寫不算。 - 每節至少寫四項： - 版本分支名與推送日期； - 更新項清單（只寫使用者能感受到的行為變化，不逐條抄提交訊息）； - 影響範圍（涉及哪些模塊／頁面、是否需後端同步、是否含破壞性變更）； - 可直接對外公告的短文（一至兩句）。 - 含破壞性變更或需後端同步時，另在 `.ai/history/breaking-changes.md` 或對接文檔留痕，細節不在此展開。 - 建立版本分支時的**首次推送**（分支上尚無內容）不強制寫日誌；其後每次帶內容的推送都必須先寫。 - 版本分支以外的推送（功能分支、整合版-dev）不強制；但合併進版本分支的那一次仍照上辦理。 ## 分支命名 - 版本分支：`x.y.z.n`，如 `2.0.0.2`；與遠端同名分支保持同步。 - 功能分支：`feature/`，`scope` 用變更主題的小寫英文短語，如 `feature/pickup-point-setting`。 - 需長期保留的功能分支：以 `keep/` 前綴標註（例如 `keep/`），使其不被刪除機制回收。 ## 刪除機制 **本機分支**符合下列任一情況時應刪除： - **落後於版本分支 3 個版本以上**。 - **已建立新的對應功能分支**（舊分支被取代）。 - **內容已完整落在版本分支或主分支**（含以 merge 承接），本機已無獨有提交。 可額外保留的分支： - 尚未併入版本分支的功能分支。 - 已標註需長期保留的功能分支（`keep/` 前綴）。 **遠端分支**： - 遠端只保留主分支與版本分支；功能分支不推遠端。 - 版本分支**統一保留**，不刪除，作為歷史演進留檔。 ## 與其他規則的關係 - 提交訊息格式見 `git-commit-message.md`。 - 迭代完成後，被新實作取代的舊實作須移除，見 `legacy-removal.md`。 - 模組與菜單結構的變更需同步 `.ai/module-registry.md`。