Pull Requests
Overview
Pull requests package a change so others can review, test, and ship it safely.
Why It Matters
A good PR reduces review time and makes the change easier to trust.
Core Concepts
- The PR should explain what changed and why.
- Smaller diffs are easier to review.
- Tests and screenshots reduce uncertainty.
Mental Models
Think of the PR as a decision record and a delivery artifact.
Best Practices
- Use a clear title and summary.
- Include how to test the change.
- Link the issue, design, or context.
Common Mistakes
- Hiding context in chat instead of the PR.
- Shipping too many unrelated changes at once.
- Leaving reviewers to guess how to verify behavior.
Trade-offs
Large PRs can bundle related work, but they increase review time and defect risk.
Decision Framework
| PR size | Best use |
|---|---|
| Small | Straightforward, focused change |
| Medium | Related changes that belong together |
| Large | Only when the work is naturally inseparable |
Examples
- “This PR fixes auth redirects and adds a regression test.”
- “Verify by logging out and opening a protected page.”
Checklists
- Is the summary clear?
- Are test steps included?
- Did I separate unrelated changes?
Senior Engineer Notes
Senior engineers make PRs easy to consume. If the reviewer has to reconstruct the story, the PR is not done yet.