GST Git 工作流程指南

本文件定義 GatherSystemTech 所有專案的 Git 工作流程標準。 適用於所有 Agent 與開發者。

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.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

1. gst-reviewer-bot 執行 Code Review 並 Approve
2. 確認無 cross-repo 依賴（App PR 需確認 GST PR 已 merge）
3. Squash Merge
4. 刪除 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