The definitive guide to writing pull requests that get merged faster and reviewed better.
A practical, opinionated playbook for developers who want to level up their pull request game. Whether you're a junior developer writing your first PR or a senior engineer mentoring a team, this guide provides battle-tested patterns, templates, and examples to make code reviews faster, healthier, and more effective.
- Philosophy
- Quick Start
- The Anatomy of a Great PR
- Templates
- Examples
- Anti-Patterns
- For Reviewers
- Advanced Topics
Great pull requests are not just about code - they're about communication, respect for reviewers' time, and enabling better software. The best PRs share these characteristics:
Every PR should answer: Why does this change exist? Great PRs tell a story that connects business value to technical implementation.
The ideal PR can be reviewed in 20-30 minutes. If it takes longer, it's probably too big. Small PRs get better reviews, ship faster, and have fewer bugs.
A reviewer shouldn't need to ask "what" or "why." The PR title, description, code comments, and commit messages should create a complete narrative.
Code review is one of the most valuable activities in software development. Great PRs make the reviewer's job easier through clarity, context, and completeness.
Before requesting review: tests pass, linting is clean, conflicts are resolved, and you've self-reviewed your own changes.
New to pull requests? Start here:
- Read: The Anatomy of a Great PR - understand the building blocks
- Use: Pick a template that matches your PR type
- Study: Review real-world examples with annotations
- Avoid: Learn from common anti-patterns
- Practice: Write your PR, then use the checklist before submitting
Reviewing PRs? Jump to the Reviewer's Guide.
A great pull request has six essential components:
- Clear, specific, and scannable
- Follows a consistent format (e.g.,
[Type] Brief description) - Examples:
- ✅
[Feature] Add user authentication with OAuth2 - ✅
[Bug] Fix memory leak in WebSocket connection handler - ❌
Update stuff(too vague) - ❌
Fix issue #1234(not self-documenting)
- ✅
The most critical part. Should include:
- What: What changed?
- Why: Why was this change necessary?
- How: How was it implemented? (for complex changes)
- Testing: How was it tested?
- Screenshots/Videos: For UI changes
- Breaking Changes: Any backwards incompatibilities?
- Related Issues: Links to tickets, discussions, or docs
- Atomic and logical (each commit = one logical change)
- Clear commit messages following Conventional Commits
- Easy to bisect if things go wrong
- Focused on one concern
- No unrelated formatting changes
- No commented-out code or debug logs
- Readable and scannable
- New features include tests
- Bug fixes include regression tests
- All tests passing in CI
- Coverage metrics maintained or improved
- Links to related PRs, issues, or documentation
- Screenshots or recordings for visual changes
- Performance benchmarks for optimization work
- Migration guide for breaking changes
📚 Deep Dive: Read the complete Anatomy Guide for detailed explanations and examples.
Copy-paste templates for common PR types:
| Template | Use Case | Link |
|---|---|---|
| Feature | New functionality | View Template |
| Bug Fix | Fixing defects | View Template |
| Refactor | Code improvements | View Template |
| Documentation | Docs updates | View Template |
| Performance | Speed/efficiency improvements | View Template |
| Security | Security patches | View Template |
Need a custom template? See our template guide.
Learn from real-world examples with detailed annotations:
- Excellent Feature PR - A full-featured implementation with great documentation
- Perfect Bug Fix - Clear problem statement and solution
- Smart Refactor - Improving code without changing behavior
- Before & After - Transforming bad PRs into great ones
Common mistakes and how to fix them:
❌ Problem: 3,000 lines changed across 47 files
✅ Solution: Break into smaller, focused PRs
❌ Problem: No description, title is "fix stuff"
✅ Solution: Write clear title and comprehensive description
❌ Problem: Includes refactoring, new feature, and bug fixes
✅ Solution: One concern per PR
❌ Problem: Marked as draft for weeks with no updates
✅ Solution: Either finish it or close it
📚 Full List: See complete anti-patterns guide with examples and fixes.
Great reviews are just as important as great PRs:
- Reviewer's Guide - How to give effective, constructive feedback
- Review Checklist - What to look for when reviewing
- Comment Templates - Effective ways to phrase feedback
- Handling Conflicts - Resolving disagreements gracefully
Key Principle: Review the code, not the person. Be kind, be specific, be helpful.
Level up your PR game:
- PR Sizing Strategies - Techniques for breaking down large work
- Stacking PRs - Managing dependent pull requests
- Draft PRs - When and how to use work-in-progress PRs
- Monorepo PRs - Special considerations for monorepos
- Migration PRs - Handling large-scale changes
- Performance PRs - Documenting benchmarks and optimizations
- Security PRs - Handling sensitive changes responsibly
MIT (c) 2026 Steven Gonzalez
Every year, developers spend millions of hours in code review. A great pull request:
- ✅ Gets reviewed faster (often same-day)
- ✅ Receives better, more thoughtful feedback
- ✅ Ships with fewer bugs
- ✅ Creates better documentation
- ✅ Builds trust with your team
- ✅ Accelerates your career
Writing great PRs is a skill - and like any skill, it can be learned, practiced, and mastered.
⭐ Star this repo if you found it helpful!
Made with ❤️ for the developer community