HIsheR
5.8 KiB
5.8 KiB
Git Branching（分支策略）
本文件定義本專案的分支層級、本地與遠端的一致性、版本分支的誕生、合併流向與分支刪除機制。所有功能開發與版本演進一律遵循。
分支層級
功能分支（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/前綴。
合併流向
- 新功能開發從目標版本分支獨立開功能分支。
- 功能分支先合併入版本分支，再由版本分支合併入整合版-dev。
- 功能分支不得直接合併進整合版-dev；版本分支不得跳過驗收直接改動。
- 落到版本分支一律用 merge，不得用 cherry-pick：cherry-pick 會為同一份改動造出第二個 SHA（本專案已發生：
0076dc0b與9748463e同一份改動），之後的合併會讓兩個 SHA 同時進入歷史，形成疊影與後續撞點。 - 合併前先算兩側改動的交集做衝突預檢；合併後對自動合併檔逐側比對，確認雙方業務改動都保留（禁止盲目
--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。