Understanding the Stacked Pull Requests Workflow
Table of Contents
Have you heard of Stacked PRs? They are becoming increasingly popular among teams looking for more efficient ways to deploy code quickly, all without compromising code quality or increasing the workload of code reviewers.
In this post, we'll take a closer look at the "Stacked Pull Requests" workflow. We'll explore the clear benefits it offers, discuss who should consider adopting it, and also address some of the challenges that are often associated with this approach.
You may be familiar with this well-known tweet that humorously suggests that reviewing 10 lines of code will reveal 10 issues, whereas reviewing 500 lines of code may appear "fine."
That tweet never fails to make me laugh, but the underlying issue is no joke: no one has the time (or energy) to thoroughly review a large Pull Request.
The larger the PR:
- the greater the chance of introducing bugs
- the more time it will take to review the code and offer feedback
In an attempt to make the code reviewer's life easier, we try to keep Pull Requests short, focusing on small features or bug fixes. While this can certainly speed up the reviewing and integration process, we all know many features can be quite complex — and there's simply no way of breaking them down easily. Additionally, one new feature often depends significantly on the progress of another.
Picture this: you are working on two high-priority features. In order to work on feature #2, feature #1 needs to be built first.
You have finished working on feature #1 and open a Pull Request. Now you need to wait until it is approved and integrated into the main branch before moving on to the next feature. You go grab a cup of coffee… and wait some more. Or you work on something else, which is not as important as feature #2.
There must be a better way, right? Well, this is exactly where Stacked Pull Requests come into play! 🔥
Let's get stacking!
What are Stacked Pull Requests?
Let's say you want to create a new "Upvotes" feature for your web application. This could involve developing a data model and an API for the backend.
In Git, the "Feature Branch Workflow" is commonly considered the standard approach. It involves creating a new branch (typically branching off from the main branch) to develop a feature or fix a bug. These branches, which are usually short-lived, are called "Feature" or "Topic" branches.
Following this convention, you would first build the data model, merge it into main, and then begin working on the API.
The "Stacked Pull Requests" approach is different. Known as dependent, incremental, or chained PRs, the concept involves generating pull requests based on other pull requests. Essentially, you are creating feature branches within feature branches, establishing a clear relationship between them.
You can create a feature branch (for instance, feature/upvotes/data-model) and subsequently create another branch (e.g., feature/upvotes/api) which is tied to the progress made in feature/upvotes/data-model.
The advantage here is clear: there's no need to merge the first branch back into main to start working on the next chapter of the feature!
We wouldn't do this with the traditional "Feature Branch" workflow because we would run into sync issues if any changes were introduced to the feature/upvotes/data-model branch. Which, let's face it, is likely to happen at some point.
Stacked Pull Requests ensure that branches stay in sync promptly, enabling you to always work with the most up-to-date code. This way, your feature/upvotes/api branch will always include the latest changes from feature/upvotes/data-model, allowing you to start working on that branch freely and, more importantly, without any delay.
The result: faster code integration! ⚡
As you can imagine, you don't need to (and most likely shouldn't!) limit yourself to only two branches. You can definitely create multiple branches that are stacked upon each other so that you can slowly progress towards the feature's final form. For example, in this scenario, it would probably make sense to also develop a user interface for the frontend.
We often stress the importance of creating small, granular commits. The mindset here is to basically apply the same approach when working with branches and pull requests.
This allows you to have more autonomy as a developer and also reduces the burden on the code reviewer — a win-win situation! ✌️
The Benefits of Stacked Pull Requests
The continuous stream of updates made possible by the "Stacked PR" workflow provides 4 distinct benefits:
-
Faster feature shipping and reduced technical debt: Stacked PRs can be extremely useful for breaking down a large pull request into smaller, more focused, and easily digestible chunks.
-
Improved collaboration: Since you can release a feature faster (even if only partially), your team members can participate and make their contributions sooner.
-
Reduced Merge Conflicts: By quickly integrating smaller changes into the
mainbranch, team members can always work with the latest updates, minimizing the likelihood of dealing with merge conflicts. -
Simplified simultaneous work on the same feature: Managing two stacked branches is much simpler than working on a single branch together.
As you see, there's a lot to like! By now, you're probably thinking:
"Well, why isn't this workflow more popular? This should be the default!"
As is often the case in Git, there are, of course, situations where Stacked Pull Requests may not make sense. But the main problem among teams is that this workflow presents some technical challenges.
Let's take a closer look at the issue at hand.
The Problem (and the Solution!)
Stacking pull requests manually can be quite cumbersome. Given that these PRs are interdependent, you will quickly realize that keeping everything in sync is quite challenging.
Whenever a change occurs in one branch, you are required to resynchronize all your branches that depend on it. This process usually entails sequentially checking out and rebasing each branch onto its main branch.
Given the frequency of updates these branches can undergo daily, the manual approach can easily become overwhelming. Although feasible, the Git CLI simply wasn't designed for this workflow.
The Solution
Thankfully, there are some tools to automate this process and make everything more manageable. And pretty soon, you can add Tower to that list!
That's right: Tower will soon support Stacked Pull Requests! You will be able to keep everything in sync directly in your favorite Git client 🔥
This will be a part of a larger project — Tower Workflows — which aims to provide you with complete control over your preferred Git workflow (you can even create your own from scratch)! We will be introducing new features gradually in several upcoming releases.
The first beta will already include the "Restacking" feature, making your life easier by allowing you to keep any branch in sync with its base. We are currently finalizing it, and we expect to ship it in June. All we can say is that things are looking G-O-O-D!
If you'd like to be among the first to try out this feature, make sure you have a look at this page and join our wailist 👇
We will be improving this feature over the next upcoming Tower releases; if you're a fan of Stacked Pull Requests, make sure you give it a shot when it's out – and let us know what you think! ✌️
