GST Git Workflow Guide

This document defines the Git workflow standards for all GatherSystemTech projects. Applicable to all Agents and developers.

1. Branch Strategy

1.1 Branch Types

Branch	Purpose	Naming
master / main	Stable release version	—
develop	Development integration (GST Framework only)	—
feature/*	Feature development	feature/{issue-id}-{english-description}
fix/*	Bug fixes	fix/{issue-id}-{english-description}
chore/*	Non-functional changes	chore/{issue-id}-{english-description}

1.2 Branch Naming Conventions

✅ feature/jop-163-velopack-manifest-fix
✅ fix/gst-114-taie-register-address
✅ chore/jop-161-rename-exe-to-jope

❌ hubert/gst-14-底層帳號管理服務擴充    ← Chinese characters prohibited
❌ feature/fix-stuff                      ← No Issue ID
❌ temp-branch                            ← Meaningless name

Important: The gitBranchName auto-generated by Linear may contain Chinese characters — never use it directly.

1.3 One Branch per Issue

✅ Correct:
  Issue JOP-163 → feature/jop-163-velopack-manifest-fix
  Issue JOP-162 → fix/jop-162-timeminutes-default-value

❌ Wrong:
  Issue JOP-163 + JOP-162 → sharing the same branch

Each Linear Issue must have its own feature branch; commits must not be mixed.

---

2. Merge Strategy

2.1 Squash Merge (Standard)

All feature branches use Squash Merge when merging into master/develop.

Squash Merge:
master:  A --- B --- C --- D
         Each commit = one PR = one Issue

Regular Merge:
master:  A --- M1 ------ M2 --- M3
              /          /       /
feature: B - C    D - E - F    G
         WIP commits all go into master

2.2 Why Squash Merge

Advantage	Description
1:1 Mapping	One commit on master = one PR = one Linear Issue
Easy Revert	Rolling back a feature only requires reverting one commit
Clean History	No "WIP", "fix typo", "oops" intermediate commits
git log = changelog	git log --oneline master serves directly as the version changelog
Audit-Friendly	Each commit is a complete, traceable change unit (FDA Part 11)

2.3 Development History Is Not Lost

After branch deletion, the development history is preserved in the GitHub PR:

git log              → View "what changed" (each commit includes PR number)
GitHub PR (#N)       → View "how it was developed" (original commits, diff, review)
Linear Issue (JOP-X) → View "why it was done" (requirements, development instructions, discussion)

The squash merge commit includes the PR number (e.g., (#5)); clicking it leads back to the PR page.

---

3. Complete Development Workflow

3.1 Feature Branch Lifecycle

1. Create an independent branch from the latest base branch
   git fetch {remote} && git checkout -b feature/{id}-{desc} {remote}/{base} --no-track

2. Develop + commit (multiple WIP commits are fine)
   git commit -m "feat({module}): {description} ({issue-id})"

3. Push to remote
   git push -u {remote} feature/{id}-{desc}

4. Create PR (via gst-pm-bot)

5. Code Review (approved by gst-reviewer-bot)

6. Squash Merge into base branch

7. Delete feature branch (GitHub auto or manual)

3.2 Commit Message Convention

{type}({module}): {description} ({issue-id})

Type	Purpose
feat	New feature
fix	Bug fix
refactor	Refactoring (no functional change)
chore	Non-functional changes (build, config)
docs	Documentation
test	Tests

Examples:

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 Prohibited Actions

Prohibited	Reason
git push --force	Tampering with history, violates FDA Part 11
Commit messages containing prohibited words	Company language policy (see COMMON-RULES)
Pushing directly to master/develop	Must go through PR
Using Chinese branch names	Git compatibility issues

---

4. Worktree Management (GST Framework)

GST Framework uses Git Worktree to support parallel multi-feature development:

GST (Main Repo)
├── [Worktree] GST-develop         → develop branch
├── [Worktree] GST-fda-part11      → feature/fda-part11
├── [Worktree] GST-smb             → feature/smb
└── [Worktree] GST-process-vision  → feature/process-vision

4.1 Worktree Advantages

• Each feature has its own working directory
• No need to stash/switch; multiple features can be developed simultaneously
• Each Agent operates in its own Worktree without interference

4.2 Worktree Considerations

• Shares the same .git directory; branch states are visible across worktrees
• git fetch only needs to be run in any one Worktree
• After merging into develop, the Test Agent runs integration tests in GST-develop

---

5. PR Workflow

5.1 Creating a PR

Use the gst-pm-bot GitHub App to create PRs:

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 Convention

{type}: {brief description}

Examples:

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 Convention

## 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}

Note: PR body must use --body-file; inline \n is not allowed.

5.4 Review and Merge

1. gst-reviewer-bot performs Code Review and Approve
2. Confirm no cross-repo dependencies (App PR requires GST PR to be merged first)
3. Squash Merge
4. Delete feature branch

---

6. Bot Integration

Bot	Purpose
gst-pm-bot	Create PR, Merge PR
gst-reviewer-bot	Code Review, Approve

6.1 Bot Usage

# 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 Naming Considerations

Remote names may not always be origin across repos:

Repo	Remote Name	Reason
GST (Worktree)	origin	Standard
GST.App.ProcessVision	master	Historical reasons
Other standalone repos	origin	Standard

Always verify before operating: git remote -v

---

8. Branch Protection Rules

8.1 Recommended Settings (All Major Repos)

Rule	Setting
Require pull request reviews	At least 1 reviewer approve
Require signed commits	GPG signing (FDA-compliant projects)
Do not allow force pushes	Prevent history tampering
Do not allow deletions	Prevent deletion of protected branches
Require status checks	Must pass before merge (if applicable)

8.2 GPG Signed Commits

Required for FDA Part 11 compliant projects:

Role	Action	Equivalent To
Developer	GPG signed commit	Developer signature
Reviewer	PR approve	Reviewer sign-off
Merger	Squash merge (signed)	Approval for release

---

9. Traceability Chain

Complete traceability:

Linear Issue (why it was done)
    ↓ Issue ID recorded in commit message
Git Commit (what changed)
    ↓ Commit includes PR number
GitHub PR (how it was developed)
    ↓ PR contains review, diff, discussion
Test Report (verification results)

Each layer can be traced back to the previous one, meeting FDA Part 11 Traceability requirements.

---

10. FAQ

10.1 Shortcut Icon Blank (After Velopack Installation)

Windows icon cache expired:

ie4uinit.exe -show

10.2 Fork Lines Not Connected After Feature Branch Merge

This is normal behavior with squash merge. Squash merge creates a new commit on master and does not draw merge lines to the feature branch.

10.3 Wrong Target Branch When Pulling

Make sure you are on the correct branch before pulling:

git checkout master
git pull

---

Document Version: v1.0 Created: 2026-03-16 Last Updated: 2026-03-16 Related Linear Issue: GST-168