create-pr

创建拉取请求

根据分支变更，创建一份结构清晰的拉取请求说明。

说明

门槛（按顺序执行）

除非每一步都通过，否则不要起草或运行 gh pr create。

1. 分支门槛： git branch --show-current 输出的不是默认分支（main、master 或仓库文档中指定的默认分支）。通过条件： 已输出分支名称，且符合要求。
2. 证据门槛： 已针对要总结的同一范围 main..HEAD（如果本地没有 main，则为 origin/main..HEAD）运行收集上下文中的命令。通过条件： 至少能说出一条提交主题和一个变更文件区域，且没有编造细节。
3. 模板门槛： 最终 PR 标题和正文中不包含未替换的占位符（<...>、TODO、TBD）。没有内容的可选部分应删除，不要留作空模板。通过条件： 快速检查后，没有尖括号占位符或填充文本。
4. 创建门槛： gh pr create 成功退出，并输出 PR URL（或 gh 输出中的 PR 编号/URL）。通过条件： 已记录 URL（或编号）；如果命令失败，不要声称 PR 已创建。

1. 收集上下文

首先，收集有关变更的信息：

# Get current branch and verify it's not main
git branch --show-current

# Get commit history for this branch
git log --oneline main..HEAD

# Get detailed commit messages for context
git log --format="### %s%n%n%b" main..HEAD

# Get file change statistics
git diff --stat main..HEAD

# Get the actual diff for understanding changes
git diff main..HEAD

2. 分析变更

根据收集到的信息，确定：

• 变更内容：对变更进行分类（功能、修复、重构、文档、测试）
• 变更原因：根据提交消息和代码变更推断动机
• 影响：破坏性变更、新依赖项、所需迁移
• 测试：新增/修改了哪些测试，以及如何手动验证

3. 检查相关问题

查找问题引用：

• 在提交消息中（例如，“fixes #123”“closes #456”）
• 在分支名称中（例如，fix/issue-123-description）
• 在已处理的代码注释或 TODO 中

4. 生成 PR 说明

使用以下模板结构创建 PR：

gh pr create --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
## Summary

<1-3 sentence overview of what this PR does and why>

## Changes

<Categorized bullet list of changes>

### Added
- <new features or capabilities>

### Changed
- <modifications to existing functionality>

### Fixed
- <bug fixes>

### Removed
- <deprecated or removed functionality>

## Motivation

<Why were these changes needed? What problem does this solve?>

## Testing

<How was this tested?>

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing performed

### Manual Testing Steps

<If applicable, steps to manually verify the changes>

## Breaking Changes

<If any, describe what breaks and migration path. Remove section if none.>

## Related Issues

<Link to related issues. Remove section if none.>

- Closes #<issue_number>
- Related to #<issue_number>

## Checklist

- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Tests pass locally
- [ ] Linting passes
- [ ] Documentation updated (if needed)
EOF
)"

可根据项目惯例附加页脚标记（例如，工具归属说明行）。如果项目没有此类惯例，则省略。

5. 标题格式

PR 标题使用约定式提交格式：

• feat(scope): add new feature
• fix(scope): correct bug behavior
• refactor(scope): restructure without behavior change
• docs(scope): update documentation
• test(scope): add or modify tests
• chore(scope): maintenance tasks

6. 应用标签

创建 PR 后，根据变更内容应用适当的标签。使用 gh pr edit <number> --add-label <label>。

先检查仓库中可用的标签：

gh label list

常见类型标签

标签	使用场景
enhancement	新功能、能力或改进
bug	Bug 修复
documentation	仅涉及文档的变更
breaking-change	面向用户的破坏性变更，需要迁移

破坏性变更的判定标准

仅当面向用户的变更要求用户修改以下内容时，才应用 breaking-change：

• 配置文件
• CLI 调用
• API 集成

除非内部重构会影响外部使用者，否则不要应用此标签。

7. 创建后

创建 PR 后：

1. 显示已应用标签的 PR URL
2. 适当时建议添加审阅者
3. 说明是否需要通过任何 CI 检查

指南

应当：

• 具体说明变更内容及原因
• 提供测试证据
• 链接相关问题
• 显著标明破坏性变更
• 删除空的可选部分

不要：

• 包含无关提交（让 PR 聚焦）
• 在说明中留下占位文本
• 跳过测试部分
• 未运行本地检查就创建 PR