Rethinking Code Reviews With Stacked PRs This post explores shift-left principles and suggests that stacked PRs will become increasingly useful. The peer code review process is an essential part of software development. It helps maintain software quality and promotes adherence to standards, project requirements, style guides, and facilitates learning and knowledge transfer. Code Review Effectiveness While the effectiveness is high for reviewing sufficiently small code changes, it drops exponentially with the increase in the size of the change. To sustain the necessary level of mental focus to be effective, large code reviews are exhausting. Usually, the longer the review duration gets, the less effective the overall review becomes: So why can’t we just restrict the size of the pull requests (PRs)? While many changes can start small, suddenly a small two-line change can grow into a 500-line refactor including multiple back-and-forth conversations with reviewers. Some engineering teams also maintain long-running feature branches as they continue working, making it hard to review. So, how do we strike the right balance? Simple. Use stacked PRs. What Are Stacked PRs? Stacked pull requests make smaller, iterative changes and are stacked on top of each other instead of bundling large monolith changes in a single pull request. Each PR in the stack focuses on one logical change only, making the review process more manageable and less time-consuming. We also wrote a post last year explaining how this help represents instead of breaking things down by files or features. code changes as a narrative Why Stacked PRs? Other than building a culture of more effective code reviews, there are a few other benefits of stacked PRs: Early Code Review Feedback Imagine that you are implementing a large feature. Instead of creating the entire feature and then requesting a code review, consider carving out the initial framework and promptly putting it up for feedback. This could potentially save you countless hours by getting early feedback on your design. Faster CI Feedback Cycle Stacked PRs support the practice because changes are continuously integrated and tested, which allows for early detection and rectification of issues. shift-left The changes are merged in bits and pieces catching any issues early vs merging one giant change hoping it does not bring down prod! Knowledge Sharing Code reviews are also wonderful for posterity. Your code changes are narrating your thought process behind implementing a feature, therefore, the breakdown of changes creates more effective knowledge transfer. It’s easier for team members to understand the changes, which promotes better knowledge sharing for the future. Staying Unblocked Waiting on getting the code reviewed and approved can be a frustrating process. With stacked PRs, the developers can work on multiple parts of a feature without waiting for reviewers to approve previous PRs What’s the Catch? So, why don’t more developers use stacked PRs for code reviews? Although this stacked PR workflow addresses both the desired practices of keeping code reviews manageable and developers productive, unfortunately, it is not supported very well natively by either Git or GitHub. As a result, have been developed across the open-source community to enable engineers to incorporate this stacking technique into the existing Git and GitHub platforms. But stacking the PRs is only part of the story. several tools Updating As we get code review feedback and we make changes to the part of the stack, we have to now rebase and resolve conflicts at all subsequent branches. Let’s take an example. Imagine that you are working on a change that requires making a schema change, a backend change, and a frontend change. With that, you can now send a simple schema change for review first, and while that’s being reviewed, you can start working on the backend and frontend. Using stacked PRs, all these 3 changes can be reviewed by 3 different reviews. In this case, you may have a stack that looks like this where , and represents the 3 branches stacked on top of each other. demo/schema demo/backend demo/frontend So far, this makes sense, but what if you got some code review comments on the schema change that requires creating a new commit? Suddenly your commit history looks like this: Now, you have to manually rebase all subsequent branches and resolve conflicts at every stage. Imagine if you have 10 stacked branches where you may have to resolve the conflicts 10 times. Merging But that’s not all, merging a PR in the stack can be a real nightmare. You have 3 options , , and to merge a PR. Let’s try to understand what goes behind the scenes in each one. squash merge rebase In the case of a commit, Git takes changes from all the existing commits of the PR and rewrites them into a single commit. In this case, no history is maintained on where those changes came from. squash A commit is a special type of Git commit that is represented by a combination of two or more commits. So, it works very similar to a commit but it also captures information about its parents. In a typical scenario, a merge commit has two parents: the last commit on the base branch (where the PR is merged), and the top commit on the feature branch that was merged. merge squash Although this approach gives more context to the commit history, it inadvertently creates a that can be undesirable. non-linear git-history Finally, in case of a and merge, Git will rewrite the commits onto the base branch. So, similar to the commit option, it will lose any history associated with the original commits. rebase squash Typically, if you are using the commit strategy while stacking PRs, your life will be a bit simpler, but most teams discourage using that strategy to keep the git-history clean. That means you are likely using either a or a merge. merge squash rebase And that creates a merge conflict for all subsequent unmerged stacked branches. In the example above, let’s say we squash merge the first branch into the mainline. It will create a new commit that contains changes of and . demo/schema D1 A1 A2 Since Git does not know where came from, and is still based on , trying to rebase on top of the mainline will create merge conflicts. D1 demo/backend A2 demo/backend Likewise, rebasing after rebasing will also cause the same issues. So if you had ten stacked branches and you squash merged one of them, you would have to resolve these conflicts nine times. demo/frontend demo/backend We are still just scratching the surface; there are such as reordering commits, splitting, folding, and renaming branches, that can create huge overhead to manage when dealing with stacked PRs. many other use cases That’s why we built stacked PRs management as part of Aviator. Why Aviator CLI Is Different Think of Aviator as an augmentation layer that sits on top of your existing tooling. Aviator connects with GitHub, Slack, Chrome, and Git CLI to provide an enhanced developer experience. Aviator CLI works seamlessly with everything else! The CLI isn’t just a layer on top of Git but also understands the context of stacks across GitHub. Let’s consider an example. Creating a Stack Creating a stack is fairly straightforward. Except in this case, we use CLI to create the branches to ensure that the stack is tracked. For instance, to create your schema branch and corresponding PR, follow the steps below. av av stack branch demo/schema # make schema changes git commit -a -m "[demo] schema changes" av pr create Since Aviator is also connected to your GitHub, it makes it easy for you to visualize the stack. Or if you want to visualize it from the terminal, you can still do that with the CLI commands: Updating the Stack Using the stack now becomes a cakewalk. You can add new commits to any branch, and simply run from anywhere in the stack to synchronize all branches. Aviator automatically rebases all the branches for you, and if there’s a real merge conflict, you just have to resolve it once. av stack sync Merging the Stack This is where Aviator tools easily stand out from any existing tooling. At Aviator, we have built one of the most advanced MergeQueue to manage auto-merging thousands of changes at scale. Aviator supports seamless integration with the CLI and stacked PRs. So to merge partial or full stack of PRs, you can assign them to Aviator MergeQueue using CLI or by posting a comment on GitHub: . av pr queue /aviator stack merge Aviator automatically handles validating, updating, and auto-merging all queued stacks in order. Now when the PRs are merged, you can this time run to update all PRs and clean out all merged PRs. av stack sync --trunk Shift-Left Is the Future Stacked PRs might initially seem like more work due to the need to break down changes into smaller parts. However, the increase in code review efficiency, faster feedback loops, and enhanced learning opportunities will surely outweigh this overhead. As we continue embracing the shift-left principles, stacked PRs will become increasingly useful. The Aviator CLI provides a great way to manage stacked PRs with a lot less tedium. The CLI is and completely free. We would love for you to try it out, and share your feedback on our . open-source discussion board At Aviator, we are building developer productivity tools from first principles to empower developers to build faster and better.
