create-pull-request

创建 Pull Request

此技能将指导你创建结构清晰、符合项目惯例和最佳实践的 GitHub 拉取请求。

前置条件检查

继续之前，请确认以下事项：

1. 检查是否已安装 gh CLI

gh --version

如果尚未安装，请告知用户：

需要 GitHub CLI（gh），但目前尚未安装。请安装：

• macOS：brew install gh
• 其他系统：https://cli.github.com/

2. 检查是否已通过 GitHub 身份验证

gh auth status

如果尚未通过身份验证，请指导用户运行 gh auth login。

3. 检查相关技能

创建 PR 之前，请检查是否有与代码审查、CI 或测试相关的技能。如果有，应先将它们作为前置步骤调用。

查找描述中包含以下内容的技能：

• “review”（例如，代码审查、PR 审查、web-design-guidelines）
• “CI” 或 “ci-fix”（例如，修复 CI 失败）
• “testing” 或 “test”（例如，运行测试、webapp-testing）

如果存在此类技能，请在继续创建 PR 之前调用它们。例如：

• 如果存在 ci-fix 技能且 CI 失败，请使用它来诊断和修复问题
• 如果 UI 有改动且存在 web-design-guidelines 技能，请使用它来审查改动
• 如果存在测试技能，请使用它来确保测试通过

只有在满足这些前置技能的要求后，才能继续创建 PR。

4. 确认工作目录干净

git status

如果存在未提交的更改，请询问用户是否要：

• 将其作为此 PR 的一部分提交
• 暂时暂存
• 丢弃（请谨慎操作）

检查是否已有 PR

收集上下文之前，请检查当前分支是否已有 PR：

gh pr list --head $(git branch --show-current) --json number,title,url

如果已有 PR：

• 显示现有 PR 的详情（编号、标题、URL）
• 询问用户是否要：
  • 查看现有 PR：gh pr view
  • 更新现有 PR（推送更多提交，PR 将自动更新）
  • 关闭现有 PR 并创建新的 PR

只有当此分支没有 PR 时，才能继续创建新的 PR。

收集上下文

1. 确认当前分支

git branch --show-current

确保当前分支不是 main 或 master。如果是，请让用户创建或切换到功能分支。

2. 查找基础分支

git remote show origin | grep "HEAD branch"

通常为 main 或 master。

3. 分析与此 PR 相关的近期提交

git log origin/main..HEAD --oneline --no-decorate

查看这些提交，了解：

• 引入了哪些更改
• PR 的范围（单项功能/修复，还是多项更改）
• 是否应合并提交或重新整理提交

4. 查看差异

git diff origin/main..HEAD --stat

这会显示哪些文件发生了更改，并有助于确定更改类型。

收集信息

从可用上下文（提交消息、分支名称、已更改文件）中收集以下信息：

要提取的信息

1. 相关 Issue 编号：在以下位置查找 #123、fixes #123 或 closes #123 等格式：

   • 提交消息
   • 分支名称（例如，fix/issue-123、feature/123-new-login）
   • 如果找到，请将其写入 PR 标题和/或描述
   • 如果未找到，则不必添加

2. 描述：此更改解决了什么问题？为什么要进行这些更改？

   • 根据提交消息和差异推断
   • 描述所做的更改

3. 更改类型：错误修复、新功能、破坏性更改、重构、外观调整、文档或工作流

   • 根据提交消息和已更改文件确定

4. 测试步骤：如何测试？可能会出现什么问题？

   • 如果修改了测试文件，请提及
   • 如果从更改中可以判断测试方法，请予以说明

智能生成 PR 标题

PR 标题应清晰且有意义。避免使用泛泛的标题，例如：

• “initial commit”
• “fix”
• “update”
• “changes”

请改用能清晰概括更改的标题。可以考虑以下方法：

1. Conventional Commits 格式

通过分析以下内容，检查项目是否使用 Conventional Commits：

• 提交消息是否包含 feat:、fix:、docs:、refactor:、test:、chore: 等模式
• 分支名称前缀，例如 feat/、fix/、docs/

如果检测到 Conventional Commits，请在 PR 标题中使用适当的前缀：

• feat: Add user authentication with OAuth
• fix: Resolve memory leak in data processing
• docs: Update API documentation for v2 endpoints
• refactor: Simplify error handling logic
• test: Add integration tests for payment flow
• chore: Update dependencies to latest versions

如果找到议题编号，请将其包含在内：

• feat: Add user authentication with OAuth (#123)
• fix(auth): Resolve memory leak in data processing (fixes #456)

2. 描述性摘要

如果未使用 Conventional Commits，请创建一个清晰、以行动为导向的标题：

• 好："为搜索结果添加分页"
• 不好："initial commit"
• 好："修复身份验证流程中的竞态条件"
• 不好："fix bug"

如果找到议题编号，请将其包含在内：

• "为搜索结果添加分页 (#123)"
• "修复身份验证流程中的竞态条件 (fixes #456)"

3. 标题生成策略

1. 查看最重要的提交消息（通常是第一条或最后一条）
2. 从差异中找出主要变更（新功能、错误修复等）
3. 提取关联的议题标题（如有）
4. 如果以上内容都无法生成合适的标题，则根据已更改的文件及其用途拟定标题
5. 如果提交消息或分支名称中有议题编号，请将其添加到标题中

Git 最佳实践

创建 PR 前，请考虑以下最佳实践：

提交规范

1. 原子提交：每次提交应代表一个独立的逻辑变更
2. 清晰的提交消息：尽可能遵循 Conventional Commits 格式
3. 不创建合并提交：优先使用变基而非合并，以保持历史记录整洁

分支管理

1. 变基到最新的 main（如有需要）：

   git fetch origin
   git rebase origin/main
   

2. 酌情压缩提交：如果有许多小型的“WIP”提交，可考虑进行交互式变基：

   git rebase -i origin/main
   

   只有在提交记录看起来杂乱且用户熟悉变基时，才建议这样做。

推送更改

确保所有提交都已推送：

git push origin HEAD

如果分支经过了变基，可能需要：

git push origin HEAD --force-with-lease

创建 Pull Request

重要：如果 .github/pull_request_template.md 存在，请阅读并使用该 PR 模板。PR 正文格式应与模板结构一致。

填写模板时：

• 如果上下文中找到议题编号，请包含该编号（例如 Fixes #123、Closes #456）
• 如果不存在模板，请创建清晰的说明，包含：
  • 更改摘要
  • 相关议题（如有）
  • 已执行的测试
  • 任何不兼容变更或值得注意的影响
• 根据提交记录和上下文中收集的信息，填写所有相关部分
• 如果模板中包含“更改类型”复选框，请勾选相应选项
• 完成所有适用的检查清单项目

Draft PR 决策

根据以下条件，决定创建 Draft PR 还是常规 PR：

在以下情况下使用 --draft 标志：

• 更改尚未完成或仍在进行中，但希望尽早获得反馈
• 测试当前未通过，需要帮助调试
• 受阻于架构决策，需要获得指导
• 创建 PR 作为书签，以便稍后继续工作
• 希望触发 CI 检查，但尚未准备好进行完整审查

在以下情况下创建常规 PR（不使用 --draft）：

• 所有测试均已通过，代码已准备好接受审查
• 更改已完成，并且你对方案有信心
• 希望尽快审查并合并 PR

使用 gh CLI 创建 PR

创建常规 PR：

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main

创建 Draft PR：

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft

创建后

创建 PR 后：

1. 在浏览器中打开 PR 进行验证

立即在浏览器中打开 PR，确认创建是否正确：

gh pr view --web

这样可以：

• 验证 PR 标题和描述是否正确显示
• 检查所有链接是否有效（例如问题引用）
• 确认差异符合预期
• 查看是否有即时 CI 状态

2. 提醒检查 CI

测试和 lint 会自动运行。请监控检查，确保全部通过。

3. 提出后续步骤（如有需要）

• 如有需要，添加审查者：gh pr edit --add-reviewer USERNAME
• 添加标签：gh pr edit --add-label "bug"

错误处理

常见问题

1. 没有领先于 main 的提交：分支没有要提交的更改

   • 询问用户是否打算在其他分支上工作

2. 分支尚未推送：远程仓库没有该分支

   • 先推送分支：git push -u origin HEAD

3. PR 已存在：该分支已有一个 PR

   • 显示现有 PR：gh pr view
   • 询问用户是否要改为更新现有 PR

4. 合并冲突：分支与基分支存在冲突

   • 指导用户解决冲突或进行变基

总结检查清单

完成前，请确保：

• 已安装并完成身份验证的 gh CLI
• 已调用相关的审查/CI/测试技能
• 此分支不存在现有 PR
• 工作目录干净
• 所有提交均已推送
• 分支已与基分支保持同步
• PR 标题清晰且有意义（而非泛泛而谈）
• 如果项目使用约定式提交格式，PR 标题应采用该格式
• 如果上下文中找到问题编号，应将其包含在标题/描述中
• PR 描述符合模板（如果存在模板）
• 已选择合适的更改类型
• 已选择正确的草稿/常规状态
• 已在浏览器中打开 PR 进行验证