A Beginner's Guide to Pull Request Stacking

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

What Is PR Stacking?

In traditional Pull Requests (PRs), the developer makes all the changes in one or more commits and then opens the PR to merge the change 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 us away from having to deliver our significant change in one go with a long review. Instead, we 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. 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 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?

We 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 our PR with the details of the entire PR stack

• rebasing and restacking PRs when we merge or close a downstream PR

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 that change a lot. Robert C Martin has a quote: “Always leave the code you’re editing a little better than you found it”. When we want to update a feature in the project, we want to leave it better than when we came to it. We could perform refactoring in the first PR to clarify the code rather than confusing the reviewer with what is added and refactored. In the next PR, we 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 essential aspect in community projects that 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 we’ve learned about PR stacking, experiment with the different PR stacking tools. Look for opportunities to use the tools in the next feature or open-source submission. As with any experiment, please note the impact that PR stacking and the tool have on our work.