Stacked Pull Requests

Jul 18, 2022

Stacked Pull Requests is a workflow strategy for splitting up code changes into more reviewable units.

Instead of having a single large pull request, a changeset is submitted as a series of PRs and branches, each as a patch to the previous branch. In effect, this treats changesets as a queue to be merged to master. With stacked pull requests, developers are unblocked from working on code that's dependent on another to-be-merged branch.

However, developers using this workflow on native git and GitHub can run into problems.

First, stacked pull requests forces you to keep multiple branches in sync. If there are changes requested to a branch, you'll have to update and sync the downstream branches. Second, if you squash your commits, you can run into some rebase issues. Third, selectively merging changes in the middle of the stack can create added complexity.

Google and Facebook both have their own tools to manage code review queues (that have their own relatively unsuccessful open-source derivatives – Phabricator and Gerrit).

GitHub already provides some support for stacked pull requests – it will automatically update the base branch of each incremental pull requests as they are merged.

There are open-source tools (e.g., ghstack) or startups (graphite.dev) to make this workflow easier on top of GitHub/git.