创建拉取请求

根据分支变更创建结构清晰的拉取请求。

指令

门禁检查（按顺序执行）

在通过每一步检查前，不要草稿化或运行 gh pr create。

1. 分支门禁：当前分支（git branch --show-current）不是默认分支（main、master 或仓库文档中定义的默认分支）。通过标准：打印出分支名称且满足此条件。
2. 证据门禁：已对将要总结的 main..HEAD（或本地 main 缺失时使用 origin/main..HEAD）范围运行了 [收集上下文](#1-收集上下文) 中的命令。通过标准：能准确说出至少一个提交主题和文件变更区域，不虚构细节。
3. 模板门禁：最终的 PR 标题和正文不含未替换的占位符（如 <...>、TODO、TBD）。可选部分若无内容则删除，不可留空占位。通过标准：快速扫描后未发现尖括号占位符或填充标记。
4. 创建门禁：gh pr create 成功退出并输出 PR URL（或 gh 输出中的 PR 编号/URL）。通过标准：记录了 URL（或编号）；若命令失败，则不得声称已创建 PR。

1. 收集上下文

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

# 获取当前分支并确认不是 main
git branch --show-current

# 获取该分支的提交历史
git log --oneline main..HEAD

# 获取详细的提交信息用于上下文
git log --format="### %s%n%n%b" main..HEAD

# 获取文件变更统计
git diff --stat main..HEAD

# 获取实际的变更差异以理解改动
git diff main..HEAD

2. 分析变更

基于收集到的信息，确定以下内容：

• 发生了什么变化：分类变更类型（功能、修复、重构、文档、测试等）
• 为何要修改：从提交信息和代码变动中推断动机
• 影响范围：是否引入破坏性变更、新增依赖、需要迁移等
• 测试情况：新增或修改了哪些测试，如何进行手动验证

3. 检查相关问题

查找与本次变更相关的任务或问题：

• 提交信息中是否有引用（如“fixes #123”、“closes #456”）
• 分支名称中是否包含问题标识（如 fix/issue-123-description）
• 代码注释或待办事项（TODO）中是否涉及本次修改的内容

4. 生成 PR 描述

使用以下模板结构创建拉取请求：

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

<1-3 句话简要说明本次 PR 的内容及原因>

## 变更内容

<按类别列出变更>

### 新增
- <新功能或能力>

### 修改
- <现有功能的调整>

### 修复
- <缺陷修复>

### 移除
- <已弃用或删除的功能>

## 动机

<为何需要这些变更？解决了什么问题？>

## 测试

<如何进行测试？>

- [ ] 添加/更新了单元测试
- [ ] 添加/更新了集成测试
- [ ] 执行了手动测试

### 手动测试步骤

<如适用，提供验证变更的具体步骤>

## 破坏性变更

<如有，请描述具体破坏点及迁移路径。若无则删除本节>

## 相关问题

<链接到相关问题。若无则删除本节>

- 关闭了 #<问题编号>
- 相关于 #<问题编号>

## 检查清单

- [ ] 代码符合项目风格规范
- [ ] 已完成自审
- [ ] 本地测试通过
- [ ] 代码格式检查通过
- [ ] 文档已更新（如需）

EOF
)"

可选地，根据项目惯例附加页脚说明（如工具署名）。若项目无此类规范，则省略。

5. 标题格式

使用常规提交格式作为 PR 标题：

• feat(scope): 添加新功能
• fix(scope): 修正错误行为
• refactor(scope): 重构代码但不改变行为
• docs(scope): 更新文档
• test(scope): 添加或修改测试
• chore(scope): 维护类任务

6. 添加标签

创建 PR 后，根据变更内容添加合适的标签。使用命令：gh pr edit <编号> --add-label <标签名>。

先查看仓库可用标签：

gh label list

常见类型标签

破坏性变更判定标准

仅当变更影响用户使用且需用户修改以下内容时才添加 breaking-change 标签：

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

内部重构除非影响外部使用者，否则不应标记为破坏性变更。

7. 创建后操作

PR 创建完成后：

1. 显示已应用标签的 PR 地址
2. 如有必要，建议添加评审人
3. 注明某些 CI 检查仍需通过

准则

应做到：

• 明确说明变更内容及其原因
• 包含测试依据
• 链接相关问题
• 突出标注破坏性变更
• 删除空的可选章节

不应：

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