qa-aman/pr-description

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

• [ ] Title: type prefix + imperative mood + under 72 chars
• [ ] Summary explains the change to someone with zero context
• [ ] Motivation explains why (not just what ticket number)
• [ ] Approach explains non-obvious decisions
• [ ] Testing section describes what was tested and how
• [ ] Screenshots included for any UI changes
• [ ] PR size is reviewable (under 400 lines of meaningful changes)