创建拉取请求

使用清晰的标题、结构化的描述和正确的分支设置创建 GitHub 拉取请求。

适用场景

• 从功能或修复分支提交变更以供评审
• 将已完成的工作合并到主分支
• 请求协作者进行代码评审
• 记录一组变更的目的和范围

输入

• 必需：包含已提交变更的功能分支
• 必需：要合并到的基准分支（通常为

  main

  ）
• 可选：要请求评审的人员
• 可选：标签或里程碑
• 可选：草稿状态

步骤

第 1 步：确保分支就绪

验证分支已与基准分支同步，且所有变更已提交：

# 检查未提交的变更
git status

# 从远程获取最新代码
git fetch origin

# 在最新的 main 上变基（或合并）
git rebase origin/main

预期结果： 分支领先于

origin/main

，无未提交的变更且无冲突。

失败处理： 如果变基产生冲突，解决冲突（参见

resolve-git-conflicts

技能），然后执行

git rebase --continue

。如果分支已严重偏离，考虑改用

git merge origin/main

。

第 2 步：审查分支上的所有变更

检查将包含在 PR 中的完整差异和提交历史：

# 查看此分支上的所有提交（不在 main 上的）
git log origin/main..HEAD --oneline

# 查看与 main 的完整差异
git diff origin/main...HEAD

# 检查分支是否跟踪远程并已推送
git status -sb

预期结果： 所有提交都与 PR 相关。差异仅显示预期的变更。

失败处理： 如果存在无关的提交，考虑使用交互式变基在创建 PR 前清理历史。

第 3 步：推送分支

# 推送分支到远程（设置上游跟踪）
git push -u origin HEAD

预期结果： 分支出现在 GitHub 远程仓库。

失败处理： 如果推送被拒绝，先使用

git pull --rebase origin <branch>

拉取并解决冲突。

第 4 步：编写 PR 标题和描述

标题控制在 70 个字符以内。详细内容写在正文中：

gh pr create --title "Add weighted mean calculation" --body "$(cat <<'EOF'
## Summary
- Implement `weighted_mean()` with NA handling and zero-weight filtering
- Add input validation for mismatched vector lengths
- Include unit tests covering edge cases

## Test plan
- [ ] `devtools::test()` passes with no failures
- [ ] Manual verification with example data
- [ ] Edge cases: empty vectors, all-NA weights, zero-length input

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

创建草稿 PR：

gh pr create --title "WIP: Add authentication" --body "..." --draft

预期结果： 在 GitHub 上创建 PR 并返回 URL。描述清楚传达了变更内容和验证方法。

失败处理： 如果

gh

未认证，运行

gh auth login

。如果基准分支不正确，使用

--base main

指定。

第 5 步：处理评审反馈

回应评审意见并推送更新：

# 查看 PR 评论
gh api repos/{owner}/{repo}/pulls/{number}/comments

# 查看 PR 检查状态
gh pr checks

# 完成修改后，提交并推送
git add <files>
git commit -m "$(cat <<'EOF'
fix: address review feedback on input validation

EOF
)"
git push

预期结果： 新的提交出现在 PR 上。评审意见已得到处理。

失败处理： 如果推送后 CI 检查失败，使用

gh pr checks

阅读检查输出并在请求重新评审前修复问题。

第 6 步：合并与清理

获得批准后：

# 合并 PR（压缩合并保持历史整洁）
gh pr merge --squash --delete-branch

# 或保留所有提交的合并
gh pr merge --merge --delete-branch

# 或变基合并（线性历史）
gh pr merge --rebase --delete-branch

合并后更新本地 main：

git checkout main
git pull origin main

预期结果： PR 已合并，远程分支已删除，本地 main 已更新。

失败处理： 如果合并被失败的检查或缺少批准所阻止，先解决这些问题。不要在未解决阻止条件的情况下强制合并。

验证清单

• PR 标题简洁（70 字符以内）且具有描述性
• PR 正文包含变更摘要和测试计划
• 分支上的所有提交都与 PR 相关
• CI 检查通过
• 分支已与基准分支同步
• 已指定评审人（如仓库设置要求）
• 差异中无敏感数据

常见问题

• PR 过大：保持 PR 专注于单个功能或修复。大型 PR 更难评审且更容易产生合并冲突。
• 缺少测试计划：始终描述如何验证变更，即使是文档类 PR。
• 分支过时：如果基准分支已大幅前进，在创建 PR 前先变基以减少合并冲突。
• 评审期间强制推送：避免对有未处理评审意见的分支强制推送。推送新提交以便评审者看到增量变更。
• 不阅读 CI 输出：在请求重新评审前检查

  gh pr checks

  。CI 失败会浪费评审者的时间。
• 忘记删除分支：合并时使用

  --delete-branch

  保持远程仓库整洁。

相关技能

• commit-changes

  - 为 PR 创建提交

• manage-git-branches

  - 分支创建和命名规范

• resolve-git-conflicts

  - 处理变基/合并时的冲突

• create-github-release

  - 合并后发布版本