创建拉取请求
使用清晰的标题、结构化的描述和正确的分支设置创建 GitHub 拉取请求。
适用场景
- 从功能或修复分支提交变更以供评审
- 将已完成的工作合并到主分支
- 请求协作者进行代码评审
- 记录一组变更的目的和范围
输入
- 必需:包含已提交变更的功能分支
- 必需:要合并到的基准分支(通常为
main) - 可选:要请求评审的人员
- 可选:标签或里程碑
- 可选:草稿状态
步骤
第 1 步:确保分支就绪
验证分支已与基准分支同步,且所有变更已提交:
# Check for uncommitted changes
git status
# Fetch latest from remote
git fetch origin
# Rebase on latest main (or merge)
git rebase origin/main
预期结果: 分支领先于 origin/main,无未提交的变更且无冲突。
失败处理: 如果变基产生冲突,解决冲突(参见 resolve-git-conflicts 技能),然后执行 git rebase --continue。如果分支已严重偏离,考虑改用 git merge origin/main。
第 2 步:审查分支上的所有变更
检查将包含在 PR 中的完整差异和提交历史:
# See all commits on this branch (not on main)
git log origin/main..HEAD --oneline
# See the full diff against main
git diff origin/main...HEAD
# Check if branch tracks remote and is pushed
git status -sb
预期结果: 所有提交都与 PR 相关。差异仅显示预期的变更。
失败处理: 如果存在无关的提交,考虑使用交互式变基在创建 PR 前清理历史。
第 3 步:推送分支
# Push branch to remote (set upstream tracking)
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 步:处理评审反馈
回应评审意见并推送更新:
# View PR comments
gh api repos/{owner}/{repo}/pulls/{number}/comments
# View PR review status
gh pr checks
# After making changes, commit and push
git add <files>
git commit -m "$(cat <<'EOF'
fix: address review feedback on input validation
EOF
)"
git push
预期结果: 新的提交出现在 PR 上。评审意见已得到处理。
失败处理: 如果推送后 CI 检查失败,使用 gh pr checks 阅读检查输出并在请求重新评审前修复问题。
第 6 步:合并与清理
获得批准后:
# Merge the PR (squash merge keeps history clean)
gh pr merge --squash --delete-branch
# Or merge with all commits preserved
gh pr merge --merge --delete-branch
# Or rebase merge (linear history)
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- 合并后发布版本