{"id":96,"date":"2025-03-30T16:21:00","date_gmt":"2025-03-30T16:21:00","guid":{"rendered":"https:\/\/blog.aviator.co\/?p=96"},"modified":"2025-09-23T12:58:56","modified_gmt":"2025-09-23T12:58:56","slug":"stacked-prs-code-changes-as-narrative","status":"publish","type":"post","link":"https:\/\/www.aviator.co\/blog\/stacked-prs-code-changes-as-narrative\/","title":{"rendered":"Stacked PRs: A Better Way to Review Code"},"content":{"rendered":"
\"stacked<\/figure>\n\n\n

Pull request review time is not linear with the size of the change. A pull request that\u2019s twice as large takes more than two times as long to review<\/strong>, or, at least, to review thoroughly. This usually means big PRs either tend to languish and grow stale or simply get rubber-stamped.<\/p>\n\n\n\n

Why? I\u2019m not entirely sure, but one of the biggest reasons is that with bigger PRs, it\u2019s harder to untangle the story that the pull request is telling. Consequently, reviewers have to spend longer trying to understand the narrative of the pull request:<\/strong> why each bit of code is changing the way it is.<\/p>\n\n\n\n

Often, big PRs start out as little PRs<\/strong>. Developers just want to fix one little bug. But, as you likely already know, little bugs aren\u2019t always as little as they seem. What should have been a ten-line change turns into a three-hundred-line refactor. It\u2019s easy to see how the story gets lots: why is a function so far away from where the bug is or at least, where we think the bug is changing so much?<\/p>\n\n\n\n

\"\"<\/a><\/figure>\n\n\n\n

Alternatively, big PRs are created in an attempt to keep hacking on a feature. In order to implement a button on the frontend, we have to write the frontend code. And the backend code. And the API layer glue. And the database schema migration. And now our PR for a single button is massive.<\/p>\n\n\n\n

What Are Stacked PRs<\/h2>\n\n\n\n

On GitHub, stacked PRs work by\u2026 well\u2026 stacking your PRs. A stack is essentially a sequence of PRs: the first PR to add the database migration is created from main<\/code>, the second is stacked<\/em> on top of the first PR, the third is stacked on top of the second, and so on. These smaller, incremental changes form a clear narrative<\/strong> when viewed as stacked diffs. Each stacked PR is created with the assumption that its ancestors will be merged (though, as we\u2019ll see below, we can handle the case where those PRs need to change as well!).<\/p>\n\n\n\n

Stacked pull requests<\/strong> work so well in this humble author\u2019s opinion because they allow developers to construct a narrative with their PRs<\/strong>. The refactoring<\/a> of the library function can be done in a separate PR from the PR that needs the new functionality introduced. The backend code can build upon the database schema definitions that were done in the previous PR.<\/p>\n\n\n\n

And, critically, PR stacking mean developers can start working on their second, third, and fourth PRs while the first PR is being reviewed<\/strong> and iterated upon.<\/p>\n\n\n\n

That\u2019s great from the reviewer’s perspective, but stacking PRs also allows the developer writing the code in the first place to move faster. They can now work on multiple parts of a feature without waiting for reviewers to approve previous PRs. <\/p>\n\n\n\n

This couldn’t be more important in a world where devs are working remotely (and across who knows how many time zones). Being blocked and waiting for your coworkers is, at best, frustrating<\/strong>. Sometimes it’s genuinely heartbreaking. Either way, the emotional and practical costs make for a bad time.<\/p>\n\n\n\n

How Stacked PRs Work <\/h2>\n\n\n\n

We\u2019ve taken a \u201cgit native\u201d approach to creating stacked pull requests, making them work smoothly with GitHub and common PRs code workflows. Stacked branches are just normal Git branches that were branched from their stack parent.<\/p>\n\n\n\n

If that sounds confusing, let\u2019s look at a quick (and realistic!) example. We want to add a like button to the website we\u2019re building, and it makes sense to do it in three phases:<\/p>\n\n\n\n

    \n
  1. Add backend service code (e.g., database schema changes and model logic)<\/li>\n\n\n\n
  2. Add a REST API interface<\/li>\n\n\n\n
  3. Implement the frontend<\/li>\n<\/ol>\n\n\n\n

    Without GitHub stacked PRs, we\u2019d have to implement this in one big PR or wait for each PR to be approved and merged before we could start on the next piece of the feature. Instead, we can open three separate PRs and have them reviewed both independently and in parallel (possibly even by different people!).<\/p>\n\n\n\n

    The Stacked Branching Strategy<\/h3>\n\n\n\n
    \n

    \ud83d\udc49 In Git, a branch is like a linked list of commits. The branch name (such as main<\/code> or like-button-rest-api<\/code>) is essentially just a pointer to a particular node in the linked list.<\/p>\n\n\n\n

    \u2020 Technically, a Git branch is closer to a <\/em>directed acyclic graph due to merge commits, but for this discussion, we\u2019ll assume there are no merge commits on the stack.<\/em><\/p>\n<\/div>\n\n\n\n

    \n\n\n\n

    Since we want to open three different PRs, we need to create three different branches. To do this, we\u2019ll simply create each new branch off of the previous branch.<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    Updating and Committing to Stacked Branches<\/h3>\n\n\n\n

    One of the primary reasons to use Aviator’s stacked PRs<\/a> is to enable easier code review<\/a> which means that it\u2019s actually pretty likely that you\u2019ll have to modify branches that have other branches stacked on top of them.<\/p>\n\n\n\n

    Modifying a stacked branch is just like modifying any other branch: perform your modifications and create a new commit!<\/p>\n\n\n\n

    However, if you commit to a branch that has children, you end up in a scenario where the parent and child branches have diverged!<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    In the diagram, like-button-frontend<\/code> doesn\u2019t contain the commit 2B<\/code> which we\u2019ve added to like-button-rest-api<\/code> which means that all of the Continuous integration<\/a> and checks we\u2019re running for like-button-frontend<\/code> are now out of date!<\/p>\n\n\n\n

    To fix this, we can rebase like-button-frontend<\/code> on top of like-button-rest-api<\/code>. This effectively \u201creplays\u201d commits 3A<\/code> and 3B<\/code> on top of 2B<\/code>:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n
    \n\n\n\n
    \n

    \ud83d\udc49 Here, we\u2019ve notated the rebased commits as 3A'<\/code> and 3B'<\/code> to illustrate the fact that, according to Git, these are actually new commits that are different from the old 3A<\/code> and 3B<\/code>. This is because Git considers the parents of a commit as part of the identity (i.e., hash) of that commit. Since 3A'<\/code> has parent 2B<\/code> and 3A<\/code> has parent 2A<\/code>, they are different commits. This is why rebasing requires a force push: Git thinks we\u2019re losing 3A<\/code> and 3B<\/code> and wants to make sure we mean to erase those commits from the branch.<\/p>\n<\/div>\n\n\n\n

    \n\n\n\n

    Stacked Branches Become Stacked PRs<\/h3>\n\n\n\n

    Since GitHub doesn\u2019t have native support for PR stacking, we have to be clever when it comes time to open PRs. If we opened a PR from like-button-frontend<\/code> into main<\/code>, GitHub would show the diff from all three branches, which defeats the whole point of using Stacked PRs!<\/p>\n\n\n\n

    Instead, we open PRs in a linked-list-like fashion:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    This turns out to work out really well! The diff for like-button-frontend<\/code> only contains the changes from commits 3A<\/code> and 3B<\/code> as intended!<\/p>\n\n\n\n

    Merge Time! (Oh, Wait Turns Out It\u2019s Hard \ud83e\udd27)<\/h3>\n\n\n\n

    Merging is a very complicated subject, and to talk about it, we need to take a quick digression into the \u201csquash merge\u201d strategy.<\/p>\n\n\n\n

    A \u201csquash merge\u201d<\/strong> isn\u2019t technically a merge in the Git sense. Instead, a squash merge generates a new commit that contains the diff from the commits on a branch and adds that commit to main<\/code>. GitHub (and many other Git hosts) will consider the branch \u201cmerged\u201d (and close the associated pull request), but Git doesn\u2019t actually consider the commits from the original branch as merged into main since the squash-merge-commit isn\u2019t technically related to any of the original commits.<\/p>\n\n\n\n

    \n\n\n\n
    \n

    \ud83d\udc49 An actual Git \u201cmerge commit\u201d<\/strong> is a commit that has two (or more!) parents: the mainline branch (i.e., the branch that is being merged into) and the branch(es) that are being merged into the mainline. Git then considers the history of the mainline branch to contain the commits that were merged in. Many codebases use squash commits instead of merge commits because the history of individual feature branches is often messy and uninteresting.<\/p>\n<\/div>\n\n\n\n

    \n\n\n\n

    Ultimately, this means we can\u2019t merge each PR in order (at least while using squash commits). Let\u2019s consider the branch diagram after we merge the first branch in the stack:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    Here, we\u2019ve added the commit 1S<\/code> to main<\/code> which represents the \u201csquash merge\u201d of the like-button-backend<\/code> branch. But, critically, Git doesn\u2019t actually consider the like-button-backend<\/code> branch merged, even though GitHub does.<\/p>\n\n\n\n

    Now when we want to merge the second branch, like-button-rest-api<\/code>, into main<\/code>, Git tries to calculate all of the commits that it needs to merge into main<\/code>. Since 1A<\/code> and 1B<\/code> are part of the history of like-button-rest-api<\/code>, and not main<\/code>, ultimately the squash merge will consist of the diff of 1A<\/code>, 1B<\/code>, 2A<\/code>, and 2B<\/code>. Since 1A<\/code> and 1B<\/code> have already been applied, this almost always results in a merge conflict.<\/p>\n\n\n\n

    Merge Time, for Real!<\/h3>\n\n\n\n

    There are a few ways to get around the merge issues presented above.<\/p>\n\n\n\n

    One option is to only merge the top branch of the stack (like-button-frontend<\/code> in the example above). This is what Aviator MergeQueue<\/a> does (unless using our fast-forward<\/em> mode<\/a> see below for details!).<\/p>\n\n\n\n

    Another option is to rebase each stacked PR after its parent is merged. This essentially means that we replay (git cherry-pick<\/code>) the commits from a stacked branch on top of the squash commit generated by merging its parent branch:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    This can cause some issues in high-throughput repositories where Aviator\u2019s parallel merge queue mode<\/a> is enabled. Since we can\u2019t start rebasing the next PR until the previous one is merged, the merge process becomes serialized on running CI for each branch in the stack (since CI is re-triggered after rebasing a branch).<\/p>\n\n\n\n

    Bonus: Aviator\u2019s Fast-forward Mode<\/h3>\n\n\n\n

    Aviator\u2019s fast-forward mode<\/a> is a subset of parallel mode that works by only fast-forwarding your mainline branch to commits with known-good CI states.<\/p>\n\n\n\n

    \n\n\n\n
    \n

    \ud83d\udc49 We talked about how Git branches are just pointers to commits above. In fast-forward mode, we simply move this pointer forward to a commit that we\u2019ve already validated (instead of merging a PR, which generates a new commit that hasn\u2019t already been validated).<\/p>\n<\/div>\n\n\n\n

    \n\n\n\n

    This means we run the validation in a new branch where we\u2019re able to squash each branch into a single commit:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    Once the checks pass for the validation branch, we fast-forward main to 3S. This means that the commit that ends up in main is the exact same (i.e., same commit hash) as the one we validated:<\/p>\n\n\n\n

    \"\"<\/figure>\n\n\n\n

    Aviator will automatically mark each of the individual PRs we created early as closed.<\/p>\n\n\n\n

    Best Practices for Working with Stacked PRs<\/h2>\n\n\n\n

    Stacked PRs work best when you keep a few simple habits in mind:<\/p>\n\n\n\n