Pull Request (PR) stacking is another name for stacked diffs, a concept that has existed for several years. We’ll go through what it is, the tools you can use and where PR stacking may be of benefit.

What is PR Stacking?

In traditional Pull Requests (PRs), the developer makes all of the changes in one or more commits and then opens the PR to merge the change back into the main branch. The approach in PR stacking instead is to separate the functionality to be delivered into pieces. Let’s say we’re working on a new POST request API. 1️⃣ The first PR could be the happy path where what we submit works okay, and that would be opened against the main branch. 2️⃣ The next piece of work could be the error scenario, when the payload is too large, and that PR would be created to merge into the branch from the first PR. 3️⃣ Another PR could be added for the scenario when the data being sent is not in a format the API can understand, and would be stacked on top of the second PR.

A PR stack moves you away from having to deliver your big change in one go with a long review but rather break it down into pieces so they can be reviewed quickly.

What are the benefits of PR Stacking?

• easier to review — the smaller changes make it easier for the reviewer to understand what is happening and they get to know the code better.
• catch problems — with smaller PRs it is easier to see when a bug is introduced both for the author and reviewer.
• less waiting — the reviews are quicker since they are simple and developers can continue developing upon their changes while waiting for reviews.
• improved communication — using stacked PRs means there is a lot more communication about the code. This is very useful when multiple developers are working together on one feature.
• clearer code changes — since the PRs are isolated to a single change it’s clearer what each change does and if coupled with good PR descriptions, it can educate the reviewers.

What tool should I use for PR Stacking?

You could perform PR stacking with the git command but it doesn’t offer any of the features of a dedicated tool such as:

• applying the changes from the current PR to all of the PRs that are stacked on it by doing an automatic rebase.
• annotating your PR with the details of the entire PR stack.
• rebasing and restacking PRs when you merge or close a downstream PR. Below you can see some available tools, as of April 2024.

Using PR stacking in a community project

A challenge in community (open source) projects is that the dependent libraries can have new security vulnerabilities or coding practices have changed a lot. Robert C Martin has a quote “Always leave the code you’re editing a little better than you found it”. When you want to update a feature in the project, you want to leave it better than when you came to it. Rather than confusing the reviewer with what is added and refactored, you could perform your refactoring in the first PR to make the code clearer. In the next PR, you could update the tests and functionality. Another PR could be stacked upon that to fix up library dependencies that are out of date.

The benefit to the reviewers is that they can see the changes and why with each PR, an important aspect in community projects which helps with communication. This leads to faster reviews and the opportunity to continue building the functionality while feedback is gathered.

What are the next steps?

Now that you’ve learned about PR stacking, experiment with the different PR stacking tools. Look for opportunities to use the tools with your next feature or open-source submission. As with any experiment, take note of the impact that PR stacking and the tool has on your work.