This chapter follows Collaborating with Git.
Pull requests are the main review surface on GitHub. Git still only sees commits and trees—the quality of collaboration shows up in PR size, description, and how feedback maps to new commits.
Size and scope
Reviewers rarely do their best work on 2,000-line diffs. Aim for PRs that:
- Change one concern (feature, fix, refactor—not all three)
- Include tests or screenshots when behavior changes
- Split follow-up work into stacked or sequential PRs when needed
If a PR must be large, add a walkthrough in the description: file order to read, risky areas, and what you intentionally left out.
Descriptions that help reviewers
A useful template:
- Why — problem or ticket link
- What — bullet summary of changes
- How to verify — commands, flags, or UI steps
- Risk — migrations, rollbacks, feature flags
Link related issues with Fixes #123 only when merge should close them. Use Related #456 when the PR helps but does not fully resolve the issue.
Commits inside the PR
Reviewers read git log on the branch. Prefer:
- Commits that compile and pass tests (CI bisect-friendly)
- Messages that explain why, not only what changed
- Conventional Commits (
feat:,fix:,chore:) when the team adopted them—for changelogs and release notes
Squash merge on the host collapses WIP commits; still keep the branch readable during review. Interactive rebase before push is fine on your branch (Merging versus rebasing).
Reviewer focus
Effective review checks:
| Area | Questions |
|---|---|
| Correctness | Edge cases, errors, concurrency |
| Security | Input validation, secrets, authz |
| Operability | Logs, metrics, rollback |
| Maintainability | Naming, duplication, test coverage |
Automate style (formatter, linter in CI) so human review spends time on design. Request changes when merge would create shared risk; approve when you would be comfortable owning production if the author vanished.
Feedback loops and new commits
Authors should push fixes to the same branch—the PR updates. Resolve conversations when addressed; re-request review when ready.
For contentious design, sync in chat or a short call, then summarize the decision in the PR so future readers see why code looks the way it does.
Merge readiness
Before merge:
- Required CI green (GitHub Actions or other checks)
- Approvals per branch protection
- No unresolved blocking threads (team policy)
- Up to date with
mainif your rules require it (merge queue or update branch)
Choose merge button strategy deliberately—squash for clean main, merge commit when preserving branch topology matters (Pull requests with and without GitHub).
Reverts and shared responsibility
When main breaks after merge, git revert on a follow-up PR is often safer than force-pushing shared history (Undoing and moving changes). Post-incident, update tests or checks so the same class of bug fails in CI next time.
Next: Git workflows for teams.
Check your understanding
Question 1 of 7
0 of 7 checked