Overview
Based on "The Pragmatic Programmer" by Hunt & Thomas. Hunt & Thomas: "It's not just code you're writing - it's communication." A PR description is a letter to your reviewers (and to your future self). It should answer: what changed, why it changed, how to verify it, and what to watch out for. A reviewer who has to read all the code to understand the PR is doing your job for you.
Workflow
Step 1: Write the title
Format: [type]: [short description in imperative mood]
Types: feat, fix, refactor, test, chore, docs
Rules:
- Imperative mood: "add pagination" not "added pagination" or "adds pagination"
- Under 72 characters
- Specific: "fix null pointer in payment processing" not "fix bug"
Step 2: Write the Summary
2-4 sentences. Answer: what does this PR do?
Write for someone who hasn't seen the issue, ticket, or conversation. They should understand the change from this paragraph alone.
Step 3: Write the Motivation (Why)
Why was this change needed? Link the ticket but don't rely on the link - links rot.
If it's a bug fix: what was broken and what impact did it have?
If it's a feature: what user need or business goal does it serve?
If it's a refactor: what was wrong with the old approach and what does the new approach enable?
Step 4: Write the Approach (How)
For non-trivial changes: describe the key technical decisions.
- Why this approach over the alternative?
- What tradeoffs were made?
- What did you try that didn't work?
Don't explain what the code does (reviewers can read it). Explain what the code does that isn't obvious from reading it.
Step 5: Write the Testing section
What did you do to verify this works?
- Unit tests added/updated?
- Manual testing steps?
- Environments tested on?
If there are no tests: say why (legacy code, trivial change, etc.).
Step 6: Add screenshots or recordings (for UI changes)
Before/after screenshots are worth 1000 words. If the change is visual, include them. Always.
Step 7: Note anything special for reviewers
- Areas of concern you want extra eyes on
- Known limitations of this approach
- Follow-up work deferred to a future PR
Template
## Summary
[2-4 sentences: what this PR does]
## Motivation
[Why this change was needed. Don't rely on the ticket link alone.]
## Approach
[Key technical decisions and why. What's non-obvious about the implementation.]
## Testing
- [ ] Unit tests: [added / updated / not applicable - reason]
- [ ] Manual testing: [steps taken]
- [ ] Environments: [local / staging / production]
## Screenshots (if UI change)
[Before] [After]
## Notes for reviewers
[Areas of concern, known limitations, follow-up work]
Anti-Patterns
1. Title that describes the ticket, not the change
Bad: "JIRA-1234 user stuff"
Good: "feat: add email verification on user signup"
2. Motivation that just links the ticket
Bad: "See JIRA-1234"
Good: "Users could sign up with typo'd email addresses and never receive activation emails, causing support tickets. This adds verification before account creation."
3. No testing section
Bad: PR with no mention of how it was tested.
Good: Even "tested manually by logging in as a new user on staging" is better than nothing.
4. 2000-line PRs
Bad: One massive PR with 15 features and 4 bug fixes.
Good: PRs should be reviewable in 30 minutes. If it's larger, split it.
Quality Checklist