Bruce Ho

Stacked PRs

4 min read

TopicsGitStacked PRs

Jump to how to create a Stacked PR

What is a Stacked PR?

Stacked PRs are a series of pull requests where each builds on the previous one. Splitting a larger change into small, focused PRs makes reviews faster, conflicts easier to resolve, and issues easier to catch. Developers can also continue with dependent work while earlier PRs are being reviewed.

Here’s an example of a stacked PR:

  • PR 1 introduces foundational changes or smaller chunks of functionality.
  • PR 2 adds more changes that depend on what was introduced in PR 1.
  • PR 3 builds on top of PR 2, and so on…

stacked-pr-sequence-diagram

Why Large PRs are bad?

Before exploring the benefits of stacked pull requests, it’s worth understanding why bundling every change into one massive PR can be problematic. If you’ve worked on a development team, you’ve likely encountered at least one of these challenges.

For the Reviewer

A large 5,000-line PR that touches multiple parts of the codebase can be overwhelming. Faced with such a large diff, reviewers may skim it and catch only the most obvious mistakes — or postpone the review because finding enough uninterrupted time feels impossible. As a result, subtle bugs and design flaws are more likely to slip through, while delayed feedback slows development and leaves the author waiting longer to move forward.

looks-fine-code-review-meme

For the Author

After spending weeks building and refining a feature, you finally submit a massive PR for review. Then reality hits: feedback reveals that you took the wrong approach, or the requirements have changed. Without earlier input, you may need to rewrite large portions of the code, or discard them entirely.

Why use Stacked PRs?

Stacked PRs address these problems by dividing work into smaller, manageable changes and enabling early, continuous feedback. This approach offers several key benefits:

  1. Enables Continuous Progress: You can begin working on dependent changes without waiting for earlier PRs to be reviewed or merged.

  2. Improves Review Quality: Small, logically focused changes are easier to understand and review thoroughly.

  3. Prevents Costly Rework: Frequent, incremental feedback catches problems early and helps avoid last-minute overhauls.

  4. Minimizes Merge Conflicts: Merging smaller changes more frequently reduces code drift and the risk of conflicts.

How to create a Stacked PRs?

stacked-pr-illustration

1. Create the First Feature Branch

Start by checking out your base branch (usually main), then create your first feature branch (e.g., branch-1):

git checkout main
git checkout -b branch-1

2. Make Changes, Push, and Create the First PR

  • Work on branch-1 by adding your changes.
  • Commit your changes locally.
  • Push branch-1 to the remote repository.
  • Open a Pull Request (PR) for branch-1 and request a review.

3. Create a New Branch for the Next PR

While the first PR is under review, create a new branch (e.g., branch-2) that builds on top of branch-1. This new branch will contain additional changes that depend on the work in branch-1:

git checkout -b branch-2

4. Repeat the Process for Additional PRs

  1. Making changes on the current branch.
  2. Push the branch to remote and create a PR for review
  3. Creating a new branch on top of the most recent branch for the next set of changes. Repeat these steps until your feature development is complete.

Preparing Stacked PRs for Review on GitHub

Here is how to prepare stacked PRs for review on GitHub. If you use a different platform, please adapt the workflow accordingly.

  1. For your first PR (at the bottom of the stack), set your stable base branch (usually main) as the target branch. github-stacked-pr1

  2. For the subsequent PRs, set the base branch to be the previous branch in the stack (e.g., branch-1). This method isolates the changes introduced in branch-2 by excluding the overlapping commits from branch-1. As a result, the diff only shows the new changes, making it easier for reviewers to understand and provide feedback on the incremental work. github-stacked-pr2

  3. Repeat step 2 for all additional PRs in the stack.

Summary

Large PRs can slow development, overwhelm reviewers, and create unnecessary bottlenecks. Stacked PRs offer a better approach by breaking changes into smaller, focused units that enable faster, more targeted, and more effective reviews.

its-purfect