contribute

Git-Town 贡献工作流 — 停下并阅读

本工作流将引导你使用 git-town 完成完整的贡献流程。

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生变化，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

⛔ 工作流强制要求

必须使用 GIT-TOWN 命令。严禁使用原始 GIT 分支命令。

步骤	✅ 正确用法	❌ 禁止用法
创建分支	git town hack	git checkout -b
更新分支	git town sync	git pull、git fetch、git merge
创建 PR	git town propose	手动使用 GitHub 界面
合并 PR	git town ship	git merge + git push

---

阶段 0：预检 — 必须完成

步骤 0.1：创建 TodoWrite

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

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

/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:scion 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

如果验证失败：

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

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

/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

步骤 0.4：与上游同步

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

git town sync

如果发生冲突：

1. 显示冲突文件
2. 等待用户解决
3. 运行 git town continue

---

阶段 1：创建功能分支

步骤 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

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

⛔ 绝不要使用 git checkout -b。务必使用：

git town hack {branch-name}

此命令会：

1. 从 origin 和 upstream 获取更新
2. 从已更新的 main 创建分支
3. 正确设置跟踪关系
4. 更新父分支链

步骤 1.3：验证分支已创建

/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

---

阶段 2：实现并提交

步骤 2.1：实现更改

用户在此处实现更改。

（此阶段由用户或其他技能处理）

步骤 2.2：暂存并提交（允许使用原始 git）

允许使用原始 git 进行提交：

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

提交消息格式：

• feat: - 新功能
• fix: - 错误修复
• docs: - 文档
• refactor: - 代码重构
• test: - 测试
• chore: - 维护

步骤 2.3：创建 PR 前同步

⛔ 绝不要使用 git pull 或 git push。务必使用：

git town sync

此命令会：

1. 从 upstream/main 拉取更改
2. 对功能分支进行变基或合并
3. 推送到 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

---

阶段 3：创建拉取请求

步骤 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

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

⛔ 绝不要手动创建 PR。务必使用：

git town propose

此命令会：

1. 将最新更改推送到 origin
2. 打开浏览器以创建 PR
3. 指向正确的上游代码库
4. 填写分支信息

创建草稿 PR：

git town propose --draft

步骤 3.3：验证 PR 已创建

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

---

阶段 4：合并（PR 获批后）

步骤 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

步骤 4.2：使用 git-town 合并

⛔ 绝不要手动合并。务必使用：

git town ship

此命令会：

1. 验证 PR 已获批准
2. 合并到 main
3. 删除功能分支（本地和远程）
4. 更新本地 main

步骤 4.3：合并后的清理

/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

---

堆叠分支（进阶）

创建子分支

如果需要将功能拆分为多个较小的 PR：

# On feature branch, create child
git town append child-feature

# Creates stack:
# main
#   └── feature
#         └── child-feature

在堆叠中切换

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

合并堆叠

从底部向上合并：

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

---

错误恢复

撤销上一个 git-town 命令

git town undo

解决冲突后继续

git town continue

同步时跳过冲突分支

git town skip

检查 git-town 状态

git town status

---

快速参考卡

┌─────────────────────────────────────────────────────────┐
│                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     │
└─────────────────────────────────────────────────────────┘

---

参数

• [feature-name] - 可选：新功能的分支名称
• --pr - 跳转到创建 PR（分支已存在）
• --ship - 跳转到合并（PR 已获批准）

示例

# Start new contribution
/git-town-workflow:contribute feat/add-dark-mode

# Create PR for existing branch
/git-town-workflow:contribute --pr

# Ship after PR approved
/git-town-workflow:contribute --ship

---

故障排除

问题	原因	解决方案
同步失败	合并冲突	解决冲突，然后运行 git town sync
分支父级错误	git-town 配置不匹配	运行 git town branch 查看／修正层级
提议失败	没有远程跟踪分支	先运行 git town sync 推送
无法合并	分支不在 main 上	先合并 PR，或使用 --ignore-parent
“无法合并”	有未提交的更改	先提交或暂存更改
PR 已存在	再次运行 propose	使用 --pr 标志查看现有 PR

执行后反思

此技能完成后，在结束任务前进行反思：

0. 确认位置。 — 通过 Glob 搜索此技能的名称，找到此 SKILL.md 的规范路径，然后再编辑。所有修正都针对此文件及其同级 references/，绝不修改其他文档。
1. 哪里失败了？ — 修正导致问题的指令。如果问题可能再次发生，将其列为反模式。
2. 哪些做法比预期更有效？ — 将其提升为推荐实践，并记录原因。
3. 哪些内容已经过时？ — 任何与实际情况不符的脚本、参考资料或外部依赖都要立即修正。
4. 记录下来。 — 每项更改都要在演进日志中记录触发原因、修正措施和证据。

不要推迟。下一次调用会继承你留下的一切。