github-pr-creation

GitHub PR 创建

创建拉取请求，并进行任务验证、测试执行和 Conventional Commits 格式检查。

当前状态

!git rev-parse --abbrev-ref HEAD 2>/dev/null !git log @{u}..HEAD --oneline 2>/dev/null || echo "(no upstream tracking)"

核心工作流

1. 确认目标分支

继续之前务必先询问用户：

Creating PR from [current-branch] to [target-branch]. Correct?

分支流	通常的目标分支
feature/*	develop
fix/*	develop
hotfix/*	main/master
develop	main/master

2. 搜索任务文档

查找说明此 PR 应完成哪些工作的任务／规格文件。常见工具对应的位置：

工具／约定	路径
Spec2Ship (s2s)	.s2s/plans/*.md（查找与分支名称或提交匹配的有效计划）
AWS Kiro	.kiro/specs/*/tasks.md
Cursor	.cursor/rules/*.md、.cursorrules
Trae	.trae/rules/*.md
GitHub Issues	gh issue list --assignee @me --state open
通用	docs/specs/、specs/、tasks.md、TODO.md

找到后，提取任务 ID、标题、描述和需求引用。

3. 分析提交

识别此分支上每个提交的类型、范围、任务引用和破坏性变更。如果存在任务文件，将提交与文档中的任务对应起来。

4. 验证任务完成情况

如果存在任务文档：

1. 根据分支名称识别主要任务（例如，feature/task-2-* -> Task 2）
2. 找出所有子任务（例如，Task 2.1、2.2、2.3）
3. 检查提交中引用了哪些子任务
4. 报告缺失的子任务

如果任务尚未完成，停止并显示状态：

Task 2 INCOMPLETE: 1/3 sub-tasks missing
- Task 2.1: done
- Task 2.2: done
- Task 2.3: MISSING

询问用户是要完成缺失的任务，还是仍要继续。

5. 运行测试

运行项目测试套件。创建 PR 前，测试必须通过。

6. 确定 PR 类型并生成标题

分支流	标题前缀
feature/* -> develop	feat(scope):
fix/* -> develop	fix(scope):
hotfix/* -> main	hotfix(scope):
develop -> main	release:
refactor/* -> develop	refactor(scope):
chore/* -> develop	chore(scope):
ci/* -> develop	ci(scope):
docs/* -> develop	docs(scope):

标题格式：<type>(<scope>): <description>

• 类型：分析得出的主要提交类型（feat > fix > refactor > ci > chore）
• 范围：提交中最常见的范围（kebab-case）
• 描述：使用祈使语气、小写、不加句号，最多 50 个字符

破坏性变更：如果任何提交包含 BREAKING CHANGE: 或类型后带有 !：

• 如果项目中存在 breaking 标签，则添加该标签
• 在 PR 正文中加入 ## Breaking changes 部分

7. 生成 PR 正文

根据 PR 类型，从 references/pr_templates.md 使用相应模板，并填入收集到的数据。

8. 建议标签

务必先检查可用标签：

gh label list

将提交类型与项目现有标签匹配。项目使用的标签名称可能与标准名称不同（例如使用 “feature” 而非 “enhancement”）。

提交类型	常见标签名称
feat	feature、enhancement
fix	bug、bugfix
refactor	refactoring、tech-debt
docs	documentation
ci	ci/cd、infrastructure
security	security
hotfix	urgent、priority:high

如果没有匹配的标签：建议创建一个。用户可能已移除默认标签，因此可以主动提出添加相关标签。

9. 确定里程碑

检查未关闭的里程碑：

gh api repos/$(gh repo view --json nameWithOwner -q '.nameWithOwner')/milestones \
  --jq '.[] | select(.state == "open") | "\(.number): \(.title)"'

• 如果只有一个进行中的里程碑：将 PR 分配给它（所有进行中的工作都属于下一个版本）
• 如果存在多个里程碑：询问用户应使用哪一个
• 如果没有里程碑：跳过（不要自动创建）

10. 创建 PR

务必先向用户展示标题、正文、标签和里程碑，并征得批准。

gh pr create \
  --title "[title]" \
  --body "$(cat <<'EOF'
[body content]
EOF
)" \
  --base [base_branch] \
  --label "[label1]" --label "[label2]" \
  --milestone "[milestone-title]" \
  --reviewer "[username]"          # if teammates are known

如果 PR 尚未准备好接受合并审查（工作仍在进行、等待 CI，或仅为触发分支上的 AI 机器人审查而创建），请使用 --draft。

重要规则

• 始终与用户确认目标分支
• 始终在创建 PR 前运行测试
• 始终在创建 PR 前展示 PR 内容以供审批
• 始终先使用 gh label list 检查可用标签，再提出建议
• 始终使用 HEREDOC 编写正文，以保留格式
• 始终为每个标签单独添加 --label（不要在同一个字符串中用逗号分隔）
• 始终检查是否有未关闭的里程碑，并在有活动里程碑时将其指定给 PR
• 绝不未经用户确认就创建 PR
• 绝不修改仓库文件（只进行只读分析）
• 绝不自动创建里程碑——只能指定现有里程碑
• 对于尚未准备好进入合并审核阶段的 PR，使用 --draft
• 团队配置或 CODEOWNERS 中已知队友时，使用 --reviewer

参考资料

• references/pr_templates.md - 各类 PR 的正文模板（功能、发布、错误修复、紧急修复、重构、文档、CI/CD）