GST Git 工作流程指南
本文件定義 GatherSystemTech 所有專案的 Git 工作流程標準。 適用於所有 Agent 與開發者。
0. 分支流總覽
GST 採 trunk-based + per-issue feature branch + squash merge 策略：每個 Linear Issue 從 main 拉一條獨立分支，開發完成後以 squash merge 回 main，分支隨即刪除。下圖以實際命名規範展示典型流程：
讀圖重點：
- 同一時間可有多條 feature branch 並行（
docs/gst-391-...與fix/gst-114-...重疊開發）；每條只服務一個 Issue。 - Squash Merge 把 feature branch 上的所有 WIP commits 壓成一個 commit 進
main，確保main上每個 commit 對應一個 Issue / PR（見 §2 Merge 策略）。 - Tag 標示版本里程碑（如
v1.2.0），通常綁在某個 PR 的 squash commit 上。 - Rebase vs Merge 的選擇：feature branch 若落後
main太多，可在開 PR 前用git fetch && git rebase origin/main同步上游；禁止git push --force改寫已 push 的歷史（見 §3.3 禁止事項）。Squash merge 階段仍由 GitHub PR 介面執行，不需手動 rebase。
1. 分支策略
1.1 分支類型
| 分支 | 用途 | 命名 |
|---|---|---|
master / main | 穩定發行版本 | — |
develop | 開發整合（僅 GST Framework） | — |
feature/* | 功能開發 | feature/{issue-id}-{english-description} |
fix/* | 問題修復 | fix/{issue-id}-{english-description} |
chore/* | 非功能性變更 | chore/{issue-id}-{english-description} |
1.2 分支命名規範
✅ feature/jop-163-velopack-manifest-fix
✅ fix/gst-114-taie-register-address
✅ chore/jop-161-rename-exe-to-jope
❌ hubert/gst-14-底層帳號管理服務擴充 ← 禁止中文
❌ feature/fix-stuff ← 無 Issue ID
❌ temp-branch ← 無意義名稱
重要：Linear 自動產生的 gitBranchName 可能包含中文，絕對不可直接使用。
1.3 每個 Issue 獨立分支
✅ 正確：
Issue JOP-163 → feature/jop-163-velopack-manifest-fix
Issue JOP-162 → fix/jop-162-timeminutes-default-value
❌ 錯誤：
Issue JOP-163 + JOP-162 → 共用同一個分支
每個 Linear Issue 必須有自己的 feature branch，不可混合 commit。
2. Merge 策略
2.1 Squash Merge（標準）
所有 feature branch 合併至 master/develop 時，使用 Squash Merge。
Squash Merge:
master: A --- B --- C --- D
每個 commit = 一個 PR = 一個 Issue
Regular Merge:
master: A --- M1 ------ M2 --- M3
/ / /
feature: B - C D - E - F G
WIP commits 全部進 master
2.2 為什麼是 Squash Merge
| 優勢 | 說明 |
|---|---|
| 1:1 對應 | master 上一個 commit = 一個 PR = 一個 Linear Issue |
| 容易 Revert | 回滾一個功能只需 revert 一個 commit |
| 歷史乾淨 | 不會有 "WIP"、"fix typo"、"oops" 等中間 commits |
| git log = changelog | git log --oneline master 直接就是版本變更記錄 |
| 稽核友善 | 每個 commit 都是完整、可追蹤的變更單元（FDA Part 11） |
2.3 開發過程不會遺失
Branch 刪除後，開發過程保留在 GitHub PR 中：
git log → 查看「改了什麼」（每個 commit 帶 PR 編號）
GitHub PR (#N) → 查看「怎麼開發的」（原始 commits、diff、review）
Linear Issue (JOP-X) → 查看「為什麼做」（需求、開發指令、討論）
Squash merge commit 帶有 PR 編號（如 (#5)），點擊即可回到 PR 頁面。
3. 完整開發流程
3.1 Feature Branch 生命週期
1. 從最新 base branch 建立獨立分支
git fetch {remote} && git checkout -b feature/{id}-{desc} {remote}/{base} --no-track
2. 開發 + commit（可以有多個 WIP commits）
git commit -m "feat({module}): {description} ({issue-id})"
3. Push 到 remote
git push -u {remote} feature/{id}-{desc}
4. 建立 PR（透過 gst-pm-bot）
5. Code Review（透過 gst-reviewer-bot approve）
6. Squash Merge 到 base branch
7. 刪除 feature branch（GitHub 自動 or 手動）
3.2 Commit Message 規範
{type}({module}): {description} ({issue-id})
| Type | 用途 |
|---|---|
feat | 新功能 |
fix | 問題修復 |
refactor | 重構（不影響功能） |
chore | 非功能性變更（build、設定） |
docs | 文件 |
test | 測試 |
範例：
feat(manifest): change requestedExecutionLevel to asInvoker (JOP-163)
fix(register): correct TAIE FC AL1/AL2 address mapping (GST-114)
refactor(ui): rename TimeSeconds to TimeMinutes (JOP-162)
3.3 禁止事項
| 禁止 | 原因 |
|---|---|
git push --force | 竄改歷史，違反 FDA Part 11 |
| Commit message 包含禁用字詞 | 公司語言規範（詳見 COMMON-RULES） |
| 直接 push 到 master/develop | 必須透過 PR |
| 使用中文分支名稱 | Git 相容性問題 |
4. Worktree 管理（GST Framework）
GST Framework 使用 Git Worktree 支援多 feature 並行開發：
GST（主 Repo）
├── [Worktree] GST-develop → develop 分支
├── [Worktree] GST-fda-part11 → feature/fda-part11
├── [Worktree] GST-smb → feature/smb
└── [Worktree] GST-process-vision → feature/process-vision
4.1 Worktree 優勢
- 每個 feature 有獨立的工作目錄
- 不需要 stash/switch，可同時開發多個 feature
- 每個 Agent 操作自己的 Worktree，不互相干擾
4.2 Worktree 注意事項
- 共用同一個
.git目錄，branch 狀態互相可見 git fetch在任一 Worktree 執行即可- 合併到 develop 後由 Test Agent 在 GST-develop 執行整合測試
5. PR 流程
5.0 PR Lifecycle 總覽
從拉分支到 PR merge 的完整流程包含 9 個步驟，期間可能因為 Review changes 或 CI 失敗回到「commit + push」階段。下圖把整段 lifecycle 與 retry loop 都畫出來：
各步驟與本章節對應：
| 步驟 | 動作 | 詳細章節 |
|---|---|---|
| 1 | 從 origin/main 拉獨立分支 | §1.3、§3.1 |
| 2 | 開發 + commit（遵循 commit message 規範） | §3.2 |
| 3 | Push 到 remote | §3.1 |
| 4 | 透過 gst-pm-bot 開 PR | §5.1 + §5.2/5.3 標題與內容規範 |
| 5–6 | CI fail / Review changes 修正後重 commit | §5.4 |
| 7 | gst-reviewer-bot 通過審查 | §5.4、§6 Bot 整合 |
| 8 | Squash Merge | §2.1 |
| 9 | Branch / Issue 自動清理 | §8 Branch Protection、§9 追蹤鏈 |
關鍵不變式：
- 步驟 6 的「修正後重 commit」必定回到步驟 2，再走一次 push → CI → Review；中間 絕對不可 用
git push --force改寫已 push 的歷史（會破壞 PR 的 review 對話與 FDA Part 11 歷史軌跡）。 - 步驟 8 的 Squash Merge 是唯一修改
main的途徑；任何直接 push 到main的嘗試都會被 §8 的 Branch Protection 擋下。 - 步驟 9 的「Branch 自動刪除」由 GitHub 設定觸發，不需要手動
git branch -D；保留分支會干擾 §0 圖中「分支流」的乾淨度。
5.1 建立 PR
使用 gst-pm-bot GitHub App 建立 PR：
pwsh -NoProfile -Command "& 'D:\WorkSpace\GatherTech\PM\scripts\Use-GitHubBot.ps1' -Bot pm -Command 'pr create --repo {repo} --head {branch} --base {base} --title \"{title}\" --body-file {body-file}'"
5.2 PR Title 規範
{type}: {brief description}
範例：
feat: implement dashboard real-time charts
fix: change manifest execution level to asInvoker for Velopack compatibility
refactor: rename TimeSeconds to TimeMinutes across UI
5.3 PR Body 規範
## Summary
- {bullet points summarizing changes}
## Changes
| File | Change |
|------|--------|
| {file} | {description} |
## Test Results
- {test results}
## Dependencies
- {GST PR #N if any, or "None"}
## Related
- Linear Issue: {Issue ID}
注意：PR body 必須使用 --body-file，不可用 inline \n。
5.4 Review 與 Merge
- gst-reviewer-bot 執行 Code Review 並 Approve
- 確認無 cross-repo 依賴（App PR 需確認 GST PR 已 merge）
- Squash Merge
- 刪除 feature branch
6. Bot 整合
| Bot | 用途 |
|---|---|
| gst-pm-bot | 建立 PR、Merge PR |
| gst-reviewer-bot | Code Review、Approve |
6.1 Bot 使用方式
# PM Bot
& 'PM\scripts\Use-GitHubBot.ps1' -Bot pm -Command '{gh command}'
# Reviewer Bot
& 'PM\scripts\Use-GitHubBot.ps1' -Bot reviewer -Command '{gh command}'
7. Remote 命名注意事項
各 repo 的 remote 名稱不一定是 origin：
| Repo | Remote 名稱 | 原因 |
|---|---|---|
| GST（Worktree） | origin | 標準 |
| GST.App.ProcessVision | master | 歷史因素 |
| 其他獨立 Repo | origin | 標準 |
操作前先確認：git remote -v
8. Branch Protection Rules
8.1 建議設定（所有主要 repo）
| 規則 | 設定 |
|---|---|
| Require pull request reviews | 至少 1 位 reviewer approve |
| Require signed commits | GPG 簽章（FDA 合規專案） |
| Do not allow force pushes | 禁止竄改歷史 |
| Do not allow deletions | 禁止刪除 protected branch |
| Require status checks | 通過才能 merge（如適用） |
8.2 GPG Signed Commits
FDA Part 11 合規專案需啟用：
| 角色 | 動作 | 等同於 |
|---|---|---|
| 開發者 | GPG signed commit | 開發者簽名 |
| 審查者 | PR approve | 審查者簽核 |
| 合併者 | Squash merge（signed） | 核准放行 |
9. 追蹤鏈
完整的可追溯性：
Linear Issue（為什麼做）
↓ Issue ID 記錄在 commit message
Git Commit（改了什麼）
↓ Commit 帶 PR 編號
GitHub PR（怎麼開發的）
↓ PR 包含 review、diff、討論
Test Report（驗證結果）
每一層都可以反向追蹤回上一層，滿足 FDA Part 11 Traceability 要求。
10. 常見問題
10.1 捷徑 icon 空白（Velopack 安裝後）
Windows icon cache 過期：
ie4uinit.exe -show
10.2 Feature branch 合併後 Fork 線條不連接
Squash merge 的正常行為。Squash merge 在 master 建新 commit，不會與 feature branch 畫合併連線。
10.3 Pull 時目標分支錯誤
確認當前在正確的 branch 上再 pull：
git checkout master
git pull
文件版本：v1.0 建立日期：2026-03-16 最後更新：2026-03-16 對應 Linear Issue：GST-168