Stacked changes: how Facebook and Google engineers stay unblocked and ship faster

POV: waiting for your pull requests to get reviewed

You just finished writing the new comments feature for your web app: you wrote the code, tested it, and put up the PR. You're under a deadline and your next highest priority task is to add reactions to those comments.

But wait a minute - the reactions code will depend on the comments code, which isn't yet merged to main. Which means you're blocked.

If you've ever found yourself in this position, you know you have three options:

1. Work on something lower-priority while you wait for your comments PR to be approved (and risk missing the deadline).

2. Interrupt your teammate to ask for a faster review.

3. Make your comments PR bigger by merging what should have been a separate reactions PR into it (which will make it harder to review and increase the chance of bugs).

Stacking your changes

“But what about the fourth option?" - you might ask. Why can’t you write the reactions branch on top of the comments branch to stay unblocked without compromising on the size of your PRs?

The blocker here isn’t Git. In fact, the reason you can’t go with option #4 is that your code review tools probably don’t support it:

• How do you tell reviewers that your reactions PR depends on the comments PR?
• How will reviewers see the relevant diff for the reactions PR (excluding the comments PR changes)?
• How can you propagate changes to the reactions PR if you ever need to update the comments PR before you land it (i.e. to address review comments)?

But suppose we did have the right tooling to make all of this easy - would you stop at just 2 PRs stacked on top of each other? Should comments really be just one PR? Or would you break it into the series of atomic changes you originally wrote: a DB change, a new endpoint to the API schema, the implementation of that endpoint, and the front-end changes that call that endpoint?

No one likes a 4,000-line pull request

I think most developers agree that smaller PRs are easier to work with:

10 lines of code = 10 issues.

500 lines of code = "looks fine."

Code reviews.

— I Am Devloper (@iamdevloper) November 5, 2013

Smaller changes help you get faster, more thorough reviews on your code, be more targeted in who you tag (why do backend engineers and designers both need to review the same change?), and experience fewer merge conflicts.

By stacking your changes, you can get all of these benefits while staying unblocked and not needing to thrash your teammates.

Introducing Graphite

This idea isn't new, and if you've worked at a company like Facebook, Google, Uber, Dropbox, or Lyft (among others), you've either had first-class support for stacked changes built into your code review platform (i.e. Phabricator at Facebook, Critique at Google) or scripts built on top of it to enable stacking. Many engineers who come from those companies seem to miss this workflow, but it has yet to make its way into the public toolchain.

I like GitHub announcing new features but really all we need is Stacked Diffs. Please?

— Dan (@dan_abramov) June 23, 2021

Stacked diffs are the biggest feature I'd love to see support added on github! https://t.co/sijkqhsGLc

— vjeux ✪ (@Vjeux) October 1, 2018

The experience I probably miss most from writing code at FB is stacked diffs. It was SO easy to split diffs/PRs and have “1 idea” per change set. I has no clue this was not a widely available feature in industry.

— Alexandra (@alexandracoding) June 30, 2020

We're among the engineers who want stacked changes back - so much so that we're building the tooling to make it accessible for everyone else.

Graphite - our platform for stacked changes - is built directly on top of Git and seamlessly syncs with GitHub. You can use it without needing anyone else on your team to change their workflows - they'll see normal PRs from you in GitHub, which they can comment on and review as they always have.

Graphite is currently in closed beta, but it's already used by engineers at some of the largest companies every day. If you're interested in being among the first to try it out, you can sign up for our waitlist starting today.

Good point is the engineering blog for Graphite. Graphite is a a powerful, modern, and opinionated code review platform for fast-moving software teams. Learn more in our introduction.