Stacked PRs: What They Are and Why You Should Care
As a developer early in your career, you've probably gotten comfortable with the basic Git workflow: create a branch, make changes, and open a pull request (PR).
But what happens when you're working on a large feature that requires multiple changes?
Enter stacked PRs – a powerful technique that can make your development process more efficient and your code reviews more effective.
What Are Stacked PRs?
Stacked PRs (also called stacked branches or stacked diffs) are a series of dependent pull requests that build on top of each other.
Instead of putting all your changes in one massive PR, you break them down into smaller, logical chunks that are reviewed separately but merge in a specific order.
Think of it like building a house:
- First PR: Pour the foundation
- Second PR: Build the walls (depends on the foundation)
- Third PR: Add the roof (depends on the walls)
Each PR represents a complete, reviewable unit of work, but they're designed to be merged in sequence.
The Problem with Big Pull Requests
Pull request review time is not linear with the size of the change. A pull request that’s twice as large takes more than two times as long to review — or, at least to review thoroughly.
This usually means big PRs either tend to languish and grow stale or simply get rubber-stamped.
Picture this: You start fixing what seems like a simple bug. Ten minutes in, you realize this "simple" fix requires:
- Updating a core utility function
- Modifying three different components
- Adding a new API endpoint
- Changing the database schema
Suddenly, your "quick fix" has turned into a 500-line monster PR. Your reviewers open it, see the size, and either:
- Put off reviewing it (who has time to review 500 lines?)
- Skim it quickly (missing potential issues)
- Get lost trying to understand how all the pieces fit together
This is where stacked PRs come in.
Stacked PRs: Breaking Down Your Story
Think of stacked PRs like writing a book. Instead of dumping the entire manuscript on your editor at once, you send:
Chapter 1: Foundation and setup
Chapter 2: Main character development
Chapter 3: Plot resolution
Each chapter builds on the previous one, but can be reviewed and understood independently.
A Real-World Example
Let's say you're adding a "Like" button to your website. Here's how you might break it down:
Main Branch
└── PR #1: Add database schema for likes
└── PR #2: Create REST API for likes
└── PR #3: Add frontend like button
Each PR tells one part of the story:
- PR #1 sets up the foundation (how we'll store likes)
- PR #2 builds the bridge (how we'll communicate likes)
- PR #3 delivers the user experience (how users will interact with likes)
Why This Approach Works Better
1. Clearer Context
Each PR has a single, focused purpose. Reviewers can understand:
- What this specific change does
- Why it's needed
- How it fits into the bigger picture
2. Faster Feedback
Instead of waiting for someone to review your massive PR, you can:
- Get early feedback on your database schema
- Start working on the API while waiting
- Adapt to feedback without massive rewrites
3. Parallel Development
You don't have to wait for everything to be perfect before moving forward:
- Work on the frontend while the backend is being reviewed
- Address feedback on each layer independently
- Keep momentum going
Example:
Title: Add REST API endpoints for post likes
This PR is #2 in the Like Button feature stack:
1. ✅ Database schema (#123)
2. 👉 REST API (this PR)
3. ⏳ Frontend implementation (#125)
This PR adds the REST API endpoints that will support the like button feature, building on the database schema from #123.
Common Challenges and Solutions
1. Changes to Lower PRs
When you need to modify a PR that others depend on:
- Make the changes in the base PR
- Update each dependent PR (usually through rebasing)
- Push all updates
- Let reviewers know what changed
2. Keeping PRs in Sync
Use clear naming conventions:
feature/likes-1-schema
feature/likes-2-api
feature/likes-3-frontend
3. Review Order
Help reviewers by:
- Clearly marking dependencies
- Getting base PRs reviewed first
- Keeping the stack depth manageable (3-4 PRs max usually)
Making the Transition
Start small:
- Pick a feature that naturally breaks into parts
- Create just 2-3 stacked PRs
- Practice the workflow
- Get feedback from your team
- Gradually tackle more complex stacks
Conclusion
Stacked PRs might seem like extra work at first, but they're an investment in code quality and team efficiency. As you grow in your career, the ability to manage complex changes through stacked PRs will become invaluable.
Start with simple stacks of 2-3 PRs, and gradually work your way up to more complex workflows as you get comfortable with the process.
Remember: The goal isn't to make your life more complicated – it's to make large changes more manageable, both for you and your reviewers. When done right, stacked PRs can significantly improve your development workflow and make you a more effective team member.
Also, if you want to get started with a production grade free and open source tool to manage stacked PRs, av has been built just for you.
Top comments (6)
I have experimented with this, but have ultimately gone with implement one small PR at a time and start working on the next branch while review is occuring.
I ended up not liking stacked PR's because this gets very tedious:
"Update each dependent PR (usually through rebasing)"
You should give 'av' a shot!
It is a command line tool that helps developers manage cross-PR dependencies. This tool also automates syncing and merging of stacked PRs. Useful when your team wants to promote a culture of smaller, incremental PRs instead of large changes, or when your workflows involve keeping multiple, dependent PRs in sync.
Stacked PRs (Pull Requests) can be a great learning experience for new developers, allowing them to manage multiple changes and get feedback on their code. It’s an excellent way to improve code quality and collaboration skills! 💻🔧
Absolutely, it is!
Well-written article, Sumit!
Thank you Shefali!