ship-it

After-Goal: Code commit, PR merge, Issue close workflow (GitHub)

Standard wrap-up process after completing a GitHub Issue implementation: commit code → push branch → create PR → merge → close Issue.

Prerequisites

• The current git repository has implemented code changes
• Known Issue number (e.g., #42）
• gh CLI is logged in (gh auth status can verify)

Workflow

Step 1: Commit code

# 1a. 检查变更状态
git status
git diff --stat HEAD

1b. Stage the files related to this Issue (do not add unrelated files)

git add

1c. Commit, with the commit message linked to the Issue

git commit -m "$(cat <<'EOF' {brief description} (#issue-number)

{optional detailed description} EOF )"

**关键规则：**
- commit message 中包含 `#issue-number` 以关联 Issue
- 只暂存当前 Issue 相关的文件，不要混入其他变更

### Step 2: 推送分支

```bash
# 如果还在 main/master 上，先创建功能分支
git checkout -b {branch-name}  # 如已在功能分支则跳过

# 推送到远程
git push -u origin {branch-name}

Branch naming suggestion:feat/issue-42-short-desc or fix/issue-42-short-desc

Step 3: Create PR

gh pr create \
  --title "{简要描述}" \
  --body "$(cat <<'EOF'
## Summary
- 实现内容概述

Closes #{issue-number}

## Test plan
- [ ] 测试项 1
- [ ] 测试项 2
EOF
)"

Key rules:

• In the PR body, write Closes #N or Fixes #N, and GitHub will automatically close the Issue after merge
• Keep the title concise, no more than 70 characters

Step 4: Merge PR

# 4a. 查看 PR 状态（确认 checks 通过）
gh pr checks

# 4b. 合入（默认 merge commit，可选 --squash 或 --rebase）
gh pr merge --squash --delete-branch

Parameter description:

• --squash: Squash into a single commit when merging (recommended)
• --rebase: Rebase merge
• --merge: Regular merge commit
• --delete-branch: Delete the remote branch after merging

Step 5: Add an implementation summary comment

When the PR is merged / the Issue is closed, always add an implementation summary comment on the Issue, so that design decisions and code changes can later be traced directly from the Issue.

Refer to note-it to organize the summary content using the four-category structure:Design Decisions、Deviations、Tradeoffs、Open Questions. When a category has no content, write None and briefly explain.

gh issue comment {issue-number} --body "$(cat <<'EOF'
## 实现总结

**核心变更**
- {从 PR body Summary 提取的实现摘要，3-5 条 bullet}

**实现亮点（Highlights）**
- {值得强调的技术亮点：性能优化、优雅设计、复用抽象、关键测试覆盖等}，或 None

**设计决策（Design Decisions）**
- {spec 模糊/未定处所做的选择及理由}，或 None

**偏离（Deviations）**
- {有意偏离 spec 之处：spec 怎么说 → 实际怎么做 → 为什么}，或 None

**权衡（Tradeoffs）**
- {考虑过的备选方案及最终选择的原因}，或 None

**待确认（Open Questions）**
- {需用户确认的假设或后续跟进项}，或 None

---
- **PR**: #{pr-number}
- **Commit**: {hash}
EOF
)"

Key rules:

• Whether auto-close or manual close, this comment must be added
• Refer to note-it 's four-category structure (Design Decisions / Deviations / Tradeoffs / Open Questions); when a category has no content, write None
• "Implementation highlights" distills the most noteworthy technical points of this implementation (performance, design, reuse, testing, etc.); if none, write None
• Extract the core changes from the Summary section of the PR body, keeping it concise (3-5 bullets)
• Append the PR number and commit hash for easy direct navigation
• If it has already been generated via /note-it to generate docs/issue#XXXX.html, you can directly reuse its four-category content and append a link to that file at the end

Step 6: Manually close the Issue (only when it was not automatically closed)

If the PR body already contains Closes #N, the Issue will be automatically closed after merge, so skip this step. Otherwise, close it manually:

gh issue close {issue-number} --reason completed

Error handling

Scenario	Handling method
gh pr checks has failing items	Check the failure reason, fix it, then append a commit and push
PR has a merge conflict	git fetch origin main && git rebase origin/main, resolve the conflict, then force push
gh pr merge is blocked by branch protection	Confirm that required reviews have been satisfied, or ask a reviewer to approve
Issue was not automatically closed after merge	Confirm that the PR body contains Closes #N, or perform Step 6 to manually gh issue close

Complete example

# 创建分支并提交
git checkout -b feat/issue-42-case-model
git add cases/case.go cases/case_test.go
git commit -m "$(cat <<'EOF'
Add Case data model and Markdown read/write (#42)

Define Case struct with YAML frontmatter + Markdown body
serialization. Provide WriteCase/ReadCase/ListCases/UpdateCase.
EOF
)"

# 推送
git push -u origin feat/issue-42-case-model

# 创建 PR
gh pr create \
  --title "Add Case data model and Markdown read/write" \
  --body "$(cat <<'EOF'
## Summary
- Define Case struct with YAML frontmatter + Markdown body
- Implement WriteCase/ReadCase/ListCases/UpdateCase functions
- Add comprehensive test coverage

Closes #42

## Test plan
- [x] Unit tests pass
- [x] go vet / lint clean
EOF
)"

# 确认 checks 通过后合入
gh pr checks
gh pr merge --squash --delete-branch

# 添加实现总结评论（参考 note-it 四类结构）
gh issue comment 42 --body "$(cat <<'EOF'
## 实现总结

**核心变更**
- Define Case struct with YAML frontmatter + Markdown body
- Implement WriteCase/ReadCase/ListCases/UpdateCase

**实现亮点（Highlights）**
- 单文件自包含存储，读写无需外部索引，测试覆盖率 100%

**设计决策（Design Decisions）**
- Markdown body 与 YAML frontmatter 分离存储，便于人工编辑与 diff

**偏离（Deviations）**
- None — 实现与 spec 一致

**权衡（Tradeoffs）**
- 选用 frontmatter 而非独立 JSON 元数据：单文件自包含，牺牲了少量解析性能

**待确认（Open Questions）**
- None

---
- **PR**: #43
- **Commit**: abc1234
EOF
)"

# 切回主分支
git checkout main
git pull