GitHub Stacked PRs: A Practical Guide to Smaller, Faster Code Reviews

Large pull requests can be hard to review thoroughly due to their complexity and difficulty in acting upon the feedback. To address this issue, GitHub Stacked PRs provide a more structured approach. This method involves dividing a large change into a sequence of smaller, dependent pull requests that can be reviewed individually.

In this guide, we will explain what GitHub Stacked PRs are, when to employ them, and how to manage a stack using the GitHub CLI. Let's consider an authentication feature as an example. We'll break it down into three layers: the user model, the authentication API, and the login interface. The organization of these layers in the stack ensures that each layer is reviewable on its own, making the overall review process more manageable.

When using GitHub Stacked PRs, it is essential to consider the order of the layers. Foundational work, such as database migrations and shared types, should be placed at the bottom, while code that depends on these foundational elements, like API routes and UI components, should be positioned above. This structure allows reviewers to focus on one concern at a time, receive feedback earlier, and have a clear understanding of the dependencies between the layers.

Moreover, GitHub can automatically handle rebase operations within the stack when lower layers undergo changes or merge. It is important to note that GitHub Stacked PRs are not suitable for every scenario. They work best for large, multi-step features where smaller, meaningful changes are more appropriate. Before creating a stack, ensure that you have a GitHub repository, the GitHub CLI version 2.0 or later installed, and the GitHub Stacked PRs extension.

Once you have these prerequisites in place, you can begin by initializing the bottom layer of your stack. After that, you can add dependent API layers and finally the UI layer. When the stack is complete, you can submit it to GitHub using the gh stack submit command. This action will push all the branches, create or update PRs for each branch, and link the PRs as a single stack on GitHub.

The submission process opens an interactive editor where you can review each PR's title and description, and decide whether it's ready for review or a draft. Alternatively, you can use the --auto flag to create new PRs as drafts immediately or add --open to make the new PRs available for review right away. In conclusion, GitHub Stacked PRs offer a practical solution for managing and reviewing large, complex changes in a systematic and efficient manner.

By breaking down a large feature into smaller, manageable layers, reviewers can focus on one concern at a time, receive feedback earlier, and have a clearer understanding of the dependencies between the layers. This approach results in smaller, more focused diffs, earlier feedback, clearer dependencies, safer high-volume development, and less manual Git work.