contribute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git-Town Contribution Workflow — STOP AND READ

Git-Town贡献工作流——请务必先阅读

This workflow guides you through a complete contribution cycle using git-town.

本工作流将指导你使用git-town完成完整的贡献周期。

⛔ WORKFLOW ENFORCEMENT

⛔ 工作流强制规则

YOU MUST USE GIT-TOWN COMMANDS. RAW GIT BRANCH COMMANDS ARE FORBIDDEN.

Step	✅ Correct	❌ Forbidden
Create branch	`git town hack`	`git checkout -b`
Update branch	`git town sync`	`git pull` , `git fetch` , `git merge`
Create PR	`git town propose`	Manual GitHub UI
Merge PR	`git town ship`	`git merge` + `git push`

你必须使用GIT-TOWN命令，禁止使用原生Git分支操作命令。

步骤	✅ 正确操作	❌ 禁止操作
创建分支	`git town hack`	`git checkout -b`
更新分支	`git town sync`	`git pull` , `git fetch` , `git merge`
创建PR	`git town propose`	手动通过GitHub UI创建
合并PR	`git town ship`	`git merge` + `git push`

Phase 0: Preflight — MANDATORY

阶段0：前置检查——强制要求

Step 0.1: Create TodoWrite

步骤0.1：创建待办项

TodoWrite with todos:
- "[Contribute] Phase 0: Verify fork workflow is configured" | in_progress
- "[Contribute] Phase 0: Check workspace is clean" | pending
- "[Contribute] Phase 0: Sync with upstream" | pending
- "[Contribute] Phase 1: GATE - Confirm feature branch creation" | pending
- "[Contribute] Phase 1: Create feature branch with git town hack" | pending
- "[Contribute] Phase 2: Implement changes" | pending
- "[Contribute] Phase 2: Commit changes (raw git allowed here)" | pending
- "[Contribute] Phase 2: Sync branch before PR" | pending
- "[Contribute] Phase 3: GATE - Confirm PR creation" | pending
- "[Contribute] Phase 3: Create PR with git town propose" | pending
- "[Contribute] Phase 4: (Optional) Ship PR with git town ship" | pending

TodoWrite with todos:
- "[Contribute] Phase 0: Verify fork workflow is configured" | in_progress
- "[Contribute] Phase 0: Check workspace is clean" | pending
- "[Contribute] Phase 0: Sync with upstream" | pending
- "[Contribute] Phase 1: GATE - Confirm feature branch creation" | pending
- "[Contribute] Phase 1: Create feature branch with git town hack" | pending
- "[Contribute] Phase 2: Implement changes" | pending
- "[Contribute] Phase 2: Commit changes (raw git allowed here)" | pending
- "[Contribute] Phase 2: Sync branch before PR" | pending
- "[Contribute] Phase 3: GATE - Confirm PR creation" | pending
- "[Contribute] Phase 3: Create PR with git town propose" | pending
- "[Contribute] Phase 4: (Optional) Ship PR with git town ship" | pending

Step 0.2: Verify Fork Workflow Configured

步骤0.2：验证Fork工作流已配置

bash

/usr/bin/env bash << 'VERIFY_FORK_EOF'
echo "=== FORK WORKFLOW VERIFICATION ==="

bash

/usr/bin/env bash << 'VERIFY_FORK_EOF'
echo "=== FORK WORKFLOW VERIFICATION ==="

Check remotes

ORIGIN=$(git remote get-url origin 2>/dev/null) UPSTREAM=$(git remote get-url upstream 2>/dev/null)

if [[ -z "$UPSTREAM" ]]; then echo "❌ FATAL: upstream remote not configured" echo "Run: /git-town-workflow:fork to configure" exit 1 fi

echo "✅ origin: $ORIGIN" echo "✅ upstream: $UPSTREAM"

ORIGIN=$(git remote get-url origin 2>/dev/null) UPSTREAM=$(git remote get-url upstream 2>/dev/null)

if [[ -z "$UPSTREAM" ]]; then echo "❌ FATAL: upstream remote not configured" echo "Run: /git-town-workflow:fork to configure" exit 1 fi

echo "✅ origin: $ORIGIN" echo "✅ upstream: $UPSTREAM"

Check git-town config

SYNC_UPSTREAM=$(git config git-town.sync-upstream 2>/dev/null) if [[ "$SYNC_UPSTREAM" != "true" ]]; then echo "⚠️ WARNING: git-town.sync-upstream is not true" echo "Run: git config git-town.sync-upstream true" fi

Check current branch

CURRENT_BRANCH=$(git branch --show-current) echo "Current branch: $CURRENT_BRANCH"

VERIFY_FORK_EOF


**If verification fails:**

AskUserQuestion with questions:

question: "Fork workflow is not configured. Run fork setup first?" header: "Setup Required" options:
- label: "Yes, run /git-town-workflow:fork now" description: "Configure fork workflow first"
- label: "No, abort" description: "Cannot proceed without fork setup" multiSelect: false

undefined

CURRENT_BRANCH=$(git branch --show-current) echo "Current branch: $CURRENT_BRANCH"

VERIFY_FORK_EOF


**如果验证失败：**

AskUserQuestion with questions:

question: "Fork workflow is not configured. Run fork setup first?" header: "Setup Required" options:
- label: "Yes, run /git-town-workflow:fork now" description: "Configure fork workflow first"
- label: "No, abort" description: "Cannot proceed without fork setup" multiSelect: false

undefined

Step 0.3: Check Workspace Clean

步骤0.3：检查工作区是否干净

bash

/usr/bin/env bash -c 'git status --porcelain'

If workspace has changes:

AskUserQuestion with questions:
- question: "Workspace has uncommitted changes. How to proceed?"
  header: "Dirty Workspace"
  options:
    - label: "Stash changes (Recommended)"
      description: "git stash, create branch, git stash pop"
    - label: "Commit changes first"
      description: "Create commit before new branch"
    - label: "Discard changes"
      description: "WARNING: Loses uncommitted work"
    - label: "Abort"
      description: "Handle manually"
  multiSelect: false

bash

/usr/bin/env bash -c 'git status --porcelain'

如果工作区有改动：

AskUserQuestion with questions:
- question: "Workspace has uncommitted changes. How to proceed?"
  header: "Dirty Workspace"
  options:
    - label: "Stash changes (Recommended)"
      description: "git stash, create branch, git stash pop"
    - label: "Commit changes first"
      description: "Create commit before new branch"
    - label: "Discard changes"
      description: "WARNING: Loses uncommitted work"
    - label: "Abort"
      description: "Handle manually"
  multiSelect: false

Step 0.4: Sync with Upstream

步骤0.4：与上游仓库同步

ALWAYS sync before creating feature branch:

bash

git town sync

If conflicts occur:

Display conflict files
Wait for user to resolve
Run
```
git town continue
```

创建功能分支前务必先同步：

bash

git town sync

如果出现冲突：

展示冲突文件
等待用户解决
执行
```
git town continue
```

Phase 1: Create Feature Branch

阶段1：创建功能分支

Step 1.1: GATE — Confirm Branch Creation

步骤1.1：关口——确认创建分支

AskUserQuestion with questions:
- question: "What is the feature branch name?"
  header: "Branch Name"
  options:
    - label: "feat/{feature-name}"
      description: "Standard feature branch"
    - label: "fix/{bug-name}"
      description: "Bug fix branch"
    - label: "docs/{doc-name}"
      description: "Documentation branch"
    - label: "Enter custom name"
      description: "I'll provide the full branch name"
  multiSelect: false

AskUserQuestion with questions:
- question: "What is the feature branch name?"
  header: "Branch Name"
  options:
    - label: "feat/{feature-name}"
      description: "Standard feature branch"
    - label: "fix/{bug-name}"
      description: "Bug fix branch"
    - label: "docs/{doc-name}"
      description: "Documentation branch"
    - label: "Enter custom name"
      description: "I'll provide the full branch name"
  multiSelect: false

Step 1.2: Create Branch with git-town

步骤1.2：使用git-town创建分支

⛔ NEVER use
git checkout -b
. ALWAYS use:

bash

git town hack {branch-name}

This command:

Fetches from origin and upstream
Creates branch from updated main
Sets up tracking correctly
Updates parent chain

⛔ 绝对不要使用
git checkout -b
，请始终使用：

bash

git town hack {branch-name}

该命令会执行以下操作：

从origin和upstream拉取最新代码
基于最新的main分支创建新分支
正确配置追踪关系
更新父级分支链

Step 1.3: Verify Branch Created

步骤1.3：验证分支创建成功

bash

/usr/bin/env bash << 'VERIFY_BRANCH_EOF'
BRANCH=$(git branch --show-current)
echo "Current branch: $BRANCH"

bash

/usr/bin/env bash << 'VERIFY_BRANCH_EOF'
BRANCH=$(git branch --show-current)
echo "Current branch: $BRANCH"

Verify parent is main

git town branch VERIFY_BRANCH_EOF

---

git town branch VERIFY_BRANCH_EOF

---

Phase 2: Implement & Commit

阶段2：实现需求与提交代码

Step 2.1: Implement Changes

步骤2.1：实现变更

User implements their changes here.

(This phase is handled by the user or other skills)

用户在此处完成代码变更。

(该阶段由用户或其他skills处理)

Step 2.2: Stage and Commit (Raw git allowed)

步骤2.2：暂存与提交（允许使用原生Git命令）

Raw git IS allowed for commits:

bash

git add .
git commit -m "feat: description of change"

Commit message format:

```
feat:
```
- New feature
```
fix:
```
- Bug fix
```
docs:
```
- Documentation
```
refactor:
```
- Code refactoring
```
test:
```
- Tests
```
chore:
```
- Maintenance

提交操作允许使用原生Git命令：

bash

git add .
git commit -m "feat: description of change"

提交信息格式：

```
feat:
```
- 新增功能
```
fix:
```
- 修复bug
```
docs:
```
- 文档更新
```
refactor:
```
- 代码重构
```
test:
```
- 测试相关
```
chore:
```
- 维护类变更

Step 2.3: Sync Before PR

步骤2.3：创建PR前同步

⛔ NEVER use
git pull
or
git push
. ALWAYS use:

bash

git town sync

This:

Pulls changes from upstream/main
Rebases/merges feature branch
Pushes to origin (your fork)

If conflicts:

AskUserQuestion with questions:
- question: "Sync encountered conflicts. What next?"
  header: "Conflicts"
  options:
    - label: "I'll resolve conflicts manually"
      description: "Fix conflicts, then run: git town continue"
    - label: "Skip conflicting changes"
      description: "Run: git town skip (may lose changes)"
    - label: "Abort sync"
      description: "Run: git town undo"
  multiSelect: false

⛔ 绝对不要使用
git pull
或
git push
，请始终使用：

bash

git town sync

该命令会执行以下操作：

拉取upstream/main的最新变更
对功能分支执行变基/合并
推送到origin（你的fork仓库）

如果出现冲突：

AskUserQuestion with questions:
- question: "Sync encountered conflicts. What next?"
  header: "Conflicts"
  options:
    - label: "I'll resolve conflicts manually"
      description: "Fix conflicts, then run: git town continue"
    - label: "Skip conflicting changes"
      description: "Run: git town skip (may lose changes)"
    - label: "Abort sync"
      description: "Run: git town undo"
  multiSelect: false

Phase 3: Create Pull Request

阶段3：创建Pull Request

Step 3.1: GATE — Confirm PR Creation

步骤3.1：关口——确认创建PR

AskUserQuestion with questions:
- question: "Ready to create a pull request to upstream?"
  header: "Create PR"
  options:
    - label: "Yes, create PR to upstream"
      description: "Run: git town propose"
    - label: "No, keep working"
      description: "Continue development, create PR later"
    - label: "Create draft PR"
      description: "Create PR but mark as draft"
  multiSelect: false

AskUserQuestion with questions:
- question: "Ready to create a pull request to upstream?"
  header: "Create PR"
  options:
    - label: "Yes, create PR to upstream"
      description: "Run: git town propose"
    - label: "No, keep working"
      description: "Continue development, create PR later"
    - label: "Create draft PR"
      description: "Create PR but mark as draft"
  multiSelect: false

Step 3.2: Create PR with git-town

步骤3.2：使用git-town创建PR

⛔ NEVER create PR manually. ALWAYS use:

bash

git town propose

This:

Pushes latest changes to origin
Opens browser to create PR
Targets correct upstream repository
Fills in branch info

For draft PR:

bash

git town propose --draft

⛔ 绝对不要手动创建PR，请始终使用：

bash

git town propose

该命令会执行以下操作：

将最新变更推送到origin
打开浏览器创建PR
自动指向正确的上游仓库
自动填充分支信息

如果要创建草稿PR：

bash

git town propose --draft

Step 3.3: Verify PR Created

步骤3.3：验证PR创建成功

bash

/usr/bin/env bash -c 'gh pr view --json url,state,title'

bash

/usr/bin/env bash -c 'gh pr view --json url,state,title'

Phase 4: Ship (After PR Approved)

阶段4：合并上线（PR审批通过后）

Step 4.1: GATE — Confirm Ship

步骤4.1：关口——确认合并上线

AskUserQuestion with questions:
- question: "Has your PR been approved and ready to merge?"
  header: "Ship PR"
  options:
    - label: "Yes, ship it (merge to main)"
      description: "Run: git town ship"
    - label: "Not yet, PR is pending review"
      description: "Wait for approval"
    - label: "PR was merged via GitHub UI"
      description: "Just cleanup local branches"
  multiSelect: false

AskUserQuestion with questions:
- question: "Has your PR been approved and ready to merge?"
  header: "Ship PR"
  options:
    - label: "Yes, ship it (merge to main)"
      description: "Run: git town ship"
    - label: "Not yet, PR is pending review"
      description: "Wait for approval"
    - label: "PR was merged via GitHub UI"
      description: "Just cleanup local branches"
  multiSelect: false

Step 4.2: Ship with git-town

步骤4.2：使用git-town合并上线

⛔ NEVER merge manually. ALWAYS use:

bash

git town ship

This:

Verifies PR is approved
Merges to main
Deletes feature branch (local + remote)
Updates local main

⛔ 绝对不要手动合并，请始终使用：

bash

git town ship

该命令会执行以下操作：

验证PR已审批通过
合并到main分支
删除功能分支（本地+远程）
更新本地main分支

Step 4.3: Post-Ship Cleanup

步骤4.3：合并后清理

bash

/usr/bin/env bash << 'CLEANUP_EOF'
echo "=== POST-SHIP STATUS ==="

bash

/usr/bin/env bash << 'CLEANUP_EOF'
echo "=== POST-SHIP STATUS ==="

Show current branch

git branch --show-current

Show recent commits on main

git log --oneline -5

Verify feature branch deleted

git branch -a | grep -v "^*" | head -10

echo "✅ Ship complete" CLEANUP_EOF

---

git branch -a | grep -v "^*" | head -10

echo "✅ Ship complete" CLEANUP_EOF

---

Stacked Branches (Advanced)

堆叠分支（高级功能）

Creating Child Branches

创建子分支

If your feature needs to be split into smaller PRs:

bash

undefined

如果你的功能需要拆分为多个更小的PR：

bash

undefined

On feature branch, create child

git town append child-feature

Creates stack:

main

└── feature

└── child-feature

undefined

undefined

Navigating Stacks

导航堆叠分支

bash

git town up      # Go to parent branch
git town down    # Go to child branch
git town branch  # Show full stack hierarchy

bash

git town up      # 切换到父分支
git town down    # 切换到子分支
git town branch  # 展示完整的堆叠层级

Shipping Stacks

合并堆叠分支

Ship from bottom up:

bash

git town ship feature        # Ships feature first
git town ship child-feature  # Then ship child

从下往上依次合并：

bash

git town ship feature        # 先合并父分支
git town ship child-feature  # 再合并子分支

Error Recovery

错误恢复

Undo Last git-town Command

撤销上一条git-town命令

bash

git town undo

bash

git town undo

Continue After Resolving Conflicts

解决冲突后继续操作

bash

git town continue

bash

git town continue

Skip Conflicting Branch in Sync

同步时跳过有冲突的分支

bash

git town skip

bash

git town skip

Check git-town Status

检查git-town状态

bash

git town status

bash

git town status

Quick Reference Card

快速参考卡

┌─────────────────────────────────────────────────────────┐
│                GIT-TOWN CONTRIBUTION FLOW               │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. SYNC         git town sync                          │
│                  ↓                                      │
│  2. BRANCH       git town hack feature-name             │
│                  ↓                                      │
│  3. COMMIT       git add . && git commit -m "..."       │
│                  ↓                                      │
│  4. SYNC         git town sync                          │
│                  ↓                                      │
│  5. PR           git town propose                       │
│                  ↓                                      │
│  6. SHIP         git town ship (after approval)         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  ⚠️  FORBIDDEN: git checkout -b, git pull, git merge    │
│  ✅ ALLOWED: git add, git commit, git log, git diff     │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                GIT-TOWN CONTRIBUTION FLOW               │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  1. SYNC         git town sync                          │
│                  ↓                                      │
│  2. BRANCH       git town hack feature-name             │
│                  ↓                                      │
│  3. COMMIT       git add . && git commit -m "..."       │
│                  ↓                                      │
│  4. SYNC         git town sync                          │
│                  ↓                                      │
│  5. PR           git town propose                       │
│                  ↓                                      │
│  6. SHIP         git town ship (after approval)         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  ⚠️  FORBIDDEN: git checkout -b, git pull, git merge    │
│  ✅ ALLOWED: git add, git commit, git log, git diff     │
└─────────────────────────────────────────────────────────┘

Arguments

参数

```
[feature-name]
```
- Optional: Branch name for new feature
```
--pr
```
- Skip to PR creation (branch already exists)
```
--ship
```
- Skip to ship (PR already approved)

```
[feature-name]
```
- 可选：新功能的分支名称
```
--pr
```
- 直接跳转到PR创建步骤（分支已存在时使用）
```
--ship
```
- 直接跳转到合并步骤（PR已审批通过时使用）

Examples

示例

bash

undefined

bash

undefined

Start new contribution

开始新的贡献

/git-town-workflow:contribute feat/add-dark-mode

Create PR for existing branch

为已存在的分支创建PR

/git-town-workflow:contribute --pr

Ship after PR approved

PR审批通过后合并上线

/git-town-workflow:contribute --ship

undefined

/git-town-workflow:contribute --ship

undefined

Troubleshooting

故障排查

Issue	Cause	Solution
Sync failed	Merge conflicts	Resolve conflicts, then `git town sync`
Branch parent wrong	git-town config mismatch	`git town branch` to view/fix hierarchy
Propose failed	No remote tracking branch	`git town sync` first to push
Ship blocked	Branch not on main	Merge PR first, or use `--ignore-parent`
"Cannot ship"	Uncommitted changes	Commit or stash changes first
PR already exists	Re-running propose	Use `--pr` flag to view existing PR

问题	原因	解决方案
同步失败	合并冲突	解决冲突后执行 `git town sync`
分支父级错误	git-town配置不匹配	执行 `git town branch` 查看/修复层级关系
创建PR失败	不存在远程追踪分支	先执行 `git town sync` 推送代码
合并被阻止	分支未基于main	先合并PR，或使用 `--ignore-parent` 参数
"无法合并"错误	存在未提交的变更	先提交或暂存变更
PR已存在	重复执行propose命令	使用 `--pr` 参数查看现有PR