HIsheR
102 lines
5.8 KiB
Markdown
102 lines
5.8 KiB
Markdown
# Git Branching（分支策略）
|
||
|
||
本文件定義本專案的分支層級、本地與遠端的一致性、版本分支的誕生、合併流向與分支刪除機制。所有功能開發與版本演進一律遵循。
|
||
|
||
## 分支層級
|
||
|
||
```text
|
||
功能分支（feature/<scope>）
|
||
↓ 先合併
|
||
版本分支（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/<scope>`；需長期保留者加 `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>`，`scope` 用變更主題的小寫英文短語，如 `feature/pickup-point-setting`。
|
||
- 需長期保留的功能分支：以 `keep/` 前綴標註（例如 `keep/<scope>`），使其不被刪除機制回收。
|
||
|
||
## 刪除機制
|
||
|
||
**本機分支**符合下列任一情況時應刪除：
|
||
|
||
- **落後於版本分支 3 個版本以上**。
|
||
- **已建立新的對應功能分支**（舊分支被取代）。
|
||
- **內容已完整落在版本分支或主分支**（含以 merge 承接），本機已無獨有提交。
|
||
|
||
可額外保留的分支：
|
||
|
||
- 尚未併入版本分支的功能分支。
|
||
- 已標註需長期保留的功能分支（`keep/` 前綴）。
|
||
|
||
**遠端分支**：
|
||
|
||
- 遠端只保留主分支與版本分支；功能分支不推遠端。
|
||
- 版本分支**統一保留**，不刪除，作為歷史演進留檔。
|
||
|
||
## 與其他規則的關係
|
||
|
||
- 提交訊息格式見 `git-commit-message.md`。
|
||
- 迭代完成後，被新實作取代的舊實作須移除，見 `legacy-removal.md`。
|
||
- 模組與菜單結構的變更需同步 `.ai/module-registry.md`。
|