A pull request is a conversation, not just a code delivery mechanism. How you write it determines how quickly it gets reviewed, how many back-and-forth comments you'll field, and how confident your team feels merging it.
After years of code review on both sides, here's what makes a PR great.
Small and focused wins every time
The single biggest predictor of a smooth review is size. A PR touching 15 files is almost impossible to review thoroughly. A PR touching 3 files with a clear purpose gets merged fast and gets better feedback.
If your feature requires 400 lines of changes, break it into sequential PRs: data layer first, then service layer, then UI. Each one is reviewable on its own.
Write the description like a changelog entry
Your description should answer: What changed? Why? How do I test it? Are there any known trade-offs?
A template that works well:
What: Added email validation on the signup form.
Why: Users were bypassing client-side checks with direct API calls.
How to test: Try submitting with an invalid email format — should see inline error.
Notes: Validation is intentionally lenient on TLD length for international domains.
Self-review before you request review
Open your own diff and read every line before tagging anyone. You'll catch at least two things you want to fix. This habit alone cuts unnecessary review cycles in half.
Respond to every comment
Even if you disagree. Especially if you disagree. Acknowledge the point, explain your reasoning, and resolve or update. Never leave a comment hanging — it signals you either didn't see it or don't care.
Use draft PRs for work in progress
If you're pushing up incomplete work to share context or get early eyes on an approach, mark it as a draft. This sets expectations and prevents people from doing a full review prematurely.
A great PR isn't just good code — it's good communication about code.
Continue reading