Create Pull Request

Create GitHub pull request with clear title, structured description, proper branch setup.

When Use

• Proposing changes from feature or fix branch for review
• Merging completed work into main branch
• Asking for code review from collaborators
• Documenting purpose and scope of set of changes

Inputs

• Required: Feature branch with committed changes
• Required: Base branch to merge into (usually main)
• Optional: Reviewers to request
• Optional: Labels or milestone
• Optional: Draft status

Steps

Step 1: Ensure Branch Is Ready

Verify branch is up to date with base and all changes committed:

# Check for uncommitted changes
git status

# Fetch latest from remote
git fetch origin

# Rebase on latest main (or merge)
git rebase origin/main

Got: Branch ahead of origin/main with no uncommitted changes, no conflicts.

If fail: Rebase conflicts? Resolve them (see resolve-git-conflicts skill), then git rebase --continue. Branch diverged far? Consider git merge origin/main instead.

Step 2: Review All Changes on the Branch

Examine full diff and commit history going into 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

Got: All commits relevant to PR. Diff shows only intended changes.

If fail: Unrelated commits present? Consider interactive rebase to clean history before creating PR.

Step 3: Push the Branch

# Push branch to remote (set upstream tracking)
git push -u origin HEAD

Got: Branch shows on GitHub remote.

If fail: Push rejected? Pull first with git pull --rebase origin <branch> and resolve conflicts.

Step 4: Write PR Title and Description

Keep title under 70 characters. Use body for details:

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
)"

For draft PRs:

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

Got: PR created on GitHub with URL returned. Description clearly tells what changed and how to test.

If fail: gh not authenticated? Run gh auth login. Wrong base branch? Specify with --base main.

Step 5: Handle Review Feedback

Respond to review comments. Push updates:

# 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

Got: New commits show on PR. Review comments addressed.

If fail: CI checks fail after pushing? Read check output with gh pr checks. Fix issues before asking for re-review.

Step 6: Merge and Clean Up

After approval:

# 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

After merge, update local main:

git checkout main
git pull origin main

Got: PR merged, remote branch deleted, local main updated.

If fail: Merge blocked by failing checks or missing approvals? Fix those first. Do not force-merge without clearing blockers.

Checks

• PR title concise (under 70 chars) and descriptive
• PR body has summary of changes and test plan
• All commits on branch relevant to PR
• CI checks pass
• Branch up to date with base branch
• Reviewers assigned (if required by repo settings)
• No sensitive data in diff

Pitfalls

• PR too large: Keep PRs focused on single feature or fix. Big PRs harder to review, more merge conflicts.
• Missing test plan: Always describe how changes can be verified, even for docs PRs.
• Stale branch: Base branch moved far ahead? Rebase before creating PR to cut merge conflicts.
• Force-pushing during review: Dodge force-pushing to branch with open review comments. Push new commits so reviewers see incremental changes.
• Not reading CI output: Check gh pr checks before asking for re-review. Failing CI wastes reviewers' time.
• Forgetting to delete branch: Use --delete-branch with merge to keep remote clean.

See Also

• commit-changes - creating commits for PR
• manage-git-branches - branch creation and naming conventions
• resolve-git-conflicts - handling conflicts during rebase/merge
• create-github-release - releasing after merge