Stacked Diffs (and why you should know about them)
Meta and Google have been using stacking for closer to a decade: a coding workflow that is very efficient for small PRs. So what is stacking, and how come it’s not more widespread in the industry?
👋 Hi, this is Gergely with a formerly subscriber-only issue of the Pragmatic Engineer Newsletter. In every issue, I cover challenges at Big Tech and startups through the lens of engineering managers and senior engineers.
The paywall for this issue was removed nearly after 3 years of publishing - when GitHub shipped stacked diffs in public review. If you’d like to stay ahead of the industry, subscribe to the weekly newsletter:
One of my biggest personal “wow” moments during my time at Uber as a developer, was when I began using stacked diffs. Stacking refers to breaking down a pull request (PR) for a feature into several, smaller PRs which all depend on each other – hence the term “stacked”. It might sound counterintuitive, but this workflow is incredibly efficient by making it easier to review and modify PRs – or “diffs” as we called them at Uber.
The concept of stacking has existed for ages at Google, but Meta was the first company to really popularize this workflow outside the company, by open sourcing its internal developer tool called Phabricator, which supports stacked diffs. To this day, Meta engineers live and breathe stacked diffs.
For today’s issue, I reached out to five former Meta software engineers for their insights on stacking. All are now cofounders, or early employees at the developer tooling startup Graphite, which builds this stacking workflow for any company using GitHub. I am a small investor in Graphite – after experiencing the major impact which stacking had on productivity at Uber, and being curious about why this tooling is not more widely available.
Today, we cover:
Stacked diffs: the concept
How Meta uses stacked diffs
Google’s approach to stacking: chaining
Stacking outside of Meta and Google
Meta’s other neat developer tools - including ones we’ve previously not covered in Inside Meta’s Engineering Culture a year back
The impact of Meta’s developer tools on the industry
Working at Meta versus working at a startup like Graphite
If you are looking for tools that support this workflow, here are some to look at:
Graphite (engineers from this company contributed to this deepdive)
Gerrit (refers to this as a patch-based approach)
1. Stacked diffs: the concept
Stacking is a tricky concept that’s much more easily understood by doing it. To help with this, we’ll explain and visualize the process separately.
Stacking explained
Tomas Reimers worked for 2.5 years at Meta, before cofounding Graphite three years ago. Here’s how he explains stacking:
‘Stacking lets you make many small PRs easily, and without having to wait for review. Traditional git workflows equate every feature with its own PR. A PR has its own branch, and is made up of several commits. The traditional, non-stacking workflow is this:
Finish a feature
Submit a PR
Await PR approval
Merge back into main once approved
‘Once the PR is merged, you want to start work on the next feature. So you branch off of main again and begin building. Even at its most seamless, this process takes a long time! The biggest time waster is that PRs sit waiting for review for hours or days. We analyzed historical data for 15 million pull requests and PRs exist which waited several years to be merged!
‘Stacking makes the unit of change an individual commit, rather than a pull request composed of several commits. With stacking, you break up larger changes into many smaller ones. This change – a commit! – can be tested, reviewed, landed, and reverted individually.
‘These collections of smaller changes, or “stacks,” can be built continuously, one on top of the other, allowing engineers to stay unblocked and to keep moving. To give a practical example, it’s pretty common that once you build a feature, you want to build the next feature using the completed one. With stacking, you don’t have to wait for the first feature to be approved and merged; you just keep working!
‘Stacking as a methodology empowers developers to bypass the delays of main branch dependency and permits continuous parallel development.’
Stacking visualized
For stacking, a visual explanation is also helpful, and here’s my attempt at one. The traditional pull request flow works as follows:
Productive engineers tend to make small-enough pull requests, which are atomic enough and easy to review. How does an engineer go about creating a series of small PRs? There are two choices:
Create a PR, then wait for this PR to be reviewed, and then create the next PR. This is time consuming!
Create PR, then, while waiting for this PR to be reviewed, start a new branch with a second new PR, to keep working.
The most common approach for productive engineers is #2. Sure, it involves a little more context switching, but it beats waiting and doing nothing, right? So a typical flow when working on several pull requests is:
But this “traditional” pull request flow doesn’t work well when PRs depend on one another. So long as PRs are completely independent, the classic flow works well enough, and you just switch between different branches, locally.
But you are blocked if you want to make changes in PR_2 that depend on changes in PR_1 being in the main branch. Then there’s no choice but to await PR_1 approval and ping reviewers, asking them to speed up the review.
In practice, what devs usually do is add more commits to PR_1, which turns it into a giant code change. This isn’t ideal, but there’s no choice because there’s no good way to “split” a PR into several independent parts. This is where stacked diffs come in.
The idea behind stacked diffs is that you can keep working on your main branch, and worry about reviews later. You check out the main branch and start working on it, make a small change, and commit this as a diff – a very small pull request. You then continue working, creating a second diff, and a third, and so on.
You still need reviews to merge these diffs but these can wait until later. So now, your workflow changes to this:
It might feel like a small change to keep working on your current branch without waiting on reviews. But this adds up to a massive productivity boost when working with small diffs and small pull requests. Let’s visualize the difference:
The real benefit of stacked diffs is that they protect your “coding streak” by ensuring it doesn’t break when completing one code change, and moving to the next:
With stacked diffs, every commit (diff) becomes a code review. And this is the main idea behind stacked diffs. Everything else is a tooling matter.
Most developers work on large and complex pieces of work, and because of this complexity, it is not reasonable to ask engineers to limit a pull request to, say, 200 changed lines at most. Sometimes one, complete piece of work can be as many as hundreds – or even thousands! – of lines long.
Diffs – which are basically commits – make it reasonable to ensure all commits are small in size. A large piece of work that changes 1,000 lines of code can be broken into three separate diffs as follows:
Scaffolding (800 lines): the “boring” but verbose stuff. Perhaps this is auto-generated code.
Core business logic (150 lines): key changes made to the code
Edge cases (50 lines): handling of cases which aren’t part of the core code
Suddenly, it’s easier to review this code and spot issues with it. It also helps better organize your work as a dev!
Interactive rebasing
In theory, stacked diffs seem like a pleasant workflow. However, things get a bit more complicated when a change is made on the main branch or in an earlier diff. Let’s take the latter case, when a reviewer requests significant changes to the first diff.
In this example, we have three stacked diffs which all depend on one another:
After we’ve finished the last code change (diff,) the code review for Diff 1 completes. The reviewer found a couple of issues and significant changes are needed to Diff1. So:
Now what? Diff2 and Diff3 cannot be landed to the main branch while they don’t contain changes from the updated Diff 1. This is exactly why we use Interactive rebasing – basically, rewriting the local git history. We execute the command git rebase -i. If the changes to Diff1 cause conflicts with Diff2, we manually select the changes we want the updated Diff2 to contain. And we do the same with Diff3:
Working with stacked diffs usually means more frequent rebasing of small diffs. When I started to use stacked diffs with Phabricator, at Uber, rebasing became almost a daily habit. This was not just because it was common to get meaningful feedback for an earlier diff in the chain that required major code changes, but because the main branch changed frequently!
Rebasing is not unique to stacked diffs, though: it’s a pain point that happens any time lots of engineers are working in the same part of the codebase. Stacked diffs actually make rebasing a little easier because the conflicts you need to merge tend to be smaller, since the diffs themselves are smaller. The most risky rebase tends to be merging a branch with hundreds or thousands of lines of changed code and dozens of conflicts.
Getting proficient at rebasing is a helpful skill for any software engineer. Working with stacked diffs forces you to master this practice! My only addition is that when using the stacking workflow, dedicated tooling for stacking — such as within Phabricator (now unmaintained as an open source project), or Graphite, Gerrit (refers to this as a patch-based approach), Sapling or ReviewStack can make rebasing a bit easer than the native git flow.
2. How Meta uses stacked diffs
Nick Yan worked at Meta for 4 years, before joining Graphite as an engineer. When he started at Meta – then Facebook – in 2017, he was surprised that the topic of stacked diffs was covered during onboarding, early on:
“We covered stacked diffs on day one. Before starting at Facebook, I had used Git in previous internships and for school projects. Obviously Meta’s codebase was a little bit larger than my COMP11 class assignments!
For engineers at Meta, stacking was the way to write and ship code, hence this being one of the first engineering topics on Bootcamp. Stacking was so central to the culture that I had a manager who regularly told me they would not accept my code unless I split it up into smaller chunks. And splitting a larger change was straightforward.
By using stacking from day one, I didn’t have to learn the ‘hard parts’ of git. I didn’t have to worry about dependency graphs, commit trees, or cherry-picking changes. Stacking felt like a much simpler data model for code that could get complicated very quickly, especially when you have a lot of engineers all working on their own features!
I remember one of my managers literally said “I’m not accepting this unless you split this up”. Small, stacked PR’s were the cultural norm and I’ve been developing that way ever since.”
Aryaman Naik worked at Meta for nearly 5 years before joining Graphite. He shared that stacked diffs are “the way” to work at the company:
“I’m not exaggerating when I say that pretty much 100% of engineers used stacking all the time. It was a cultural norm and was the expected workflow you were supposed to follow. Stacking was so ubiquitous that when I left Meta, I was shocked to learn that stacking was a concept unique to Meta and a select few other companies. An engineer who used to work at Meta doesn’t know how not to stack.”
Why is stacking considered a better way of working at Meta? Tomas Reimers – cofounder of Graphite – worked on mobile product infra for two and a half years at Meta. He said:
“At its core, stacking allows devs to keep developing quickly, doing this by helping avoid them getting blocked by waiting on code reviews.
Stacked PRs, stacked changes, and stacked diffs are better than having several individual PRs because you have to wait less, thanks to the concept of “dependent changes.” Say you have a “child” feature that depends on work yet to be merged; with stacking, you don’t have to wait for the “parent” feature to land, you can continue to develop while it is in review.
Also, you can scale this way of “dependent” working to stacks of 5, 10 or even 20 pull requests – I’ve done this! Once your work is ready, you can merge all these PRs as a single stack, making the merge process seamless.”
Jacob Gold worked on messaging infrastructure at Meta for 2 years, before joining Graphite as a founding engineer. He also saw the benefit of not having to wait around when stacking:
“Working in many small diffs helps ease the burden of rebasing against trunk, compared to using large, long-lived branches. It’s also nice because you can continue to add to your stack while waiting on specific stakeholders to review your changes — since there might be different reviewers on different parts of the stack who review at different times.”
3. Google’s approach to stacking: chaining
While the name “stacked diffs” originated at Meta and its initially internal-only Phabricator product, the earliest example of stacking I’ve found is from Google.
Google uses a concept identical to stacking, but calls it “chaining.” The Big Tech giant calls its code changes CLs (changelist,) similar to what most tech teams call pull requests.
Google is also big on having small, easy-to-review CLs and chained CLs. Each CL being small-sized is how they do this. The company uses an internal, customized version of Mercurial for source control, internally referred to as Piper. Within Piper, Google’s tooling allows for the creation of ‘chained CLs’ which is pretty much what stacked diffs are. In this tooling, one can navigate through each CL individually. But what about when a CL gets changed, and this change needs to propagate to the child CLs?
‘hg evolve’ is the command used to “evolve” changes in the dependency tree; it’s the equivalent of git’s interactive rebasing. Take this example, where there are 3 CLs dependent on each other:
Say you get a review that suggests making significant-enough changes to CL1. Once these changes are made, you need to update CL2 and CL3, so run ‘hg evolve’ and manually resolve conflicts in CL2 and CL3.
An important note with ‘hg evolve’ is that if you update CL1 but don’t run ‘hg evolve,’ then CL2 and CL3 become orphan CLs that cannot be merged!
Google awards fun badges for perfect binary CLs trees. In what is perfectly fitting for a company with a geeky culture, a developer is awarded a badge when they create a chained CL tree in the shape of a perfect binary tree. Pulling this off is not straightforward as each CL must have precisely two children, like this:
Awarding badges for perfect binary tree CLs might be a bit over the top, but encouraging small CLs is on point, while aiming for small CLs is part of Google’s engineering culture.
4. Stacking outside of Meta and Google
Google has not opened up its source control system, so chained CLs remain available only to the company.
Meta, on the other hand, open sourced its internal developer tool, Phabricator, in 2011. It was around 2016 that the Differential tool was open sourced, which had support for stacked diffs. From 2015 until 2021, a company called Phacility – founded by former Facebook engineer and Phabricator lead Evan Priestley – offered paid support for Phabricator. As of 2021, Phabricator is no longer maintained by Phacility.
Companies using Phabricator are the majority of tech companies that introduced stacked diffs to their workflows after adopting Phabricator. In 2020, more than 200 companies used Phabricator. Companies using the tool back then included Asana, Biktm Disqus, Dropbox, Groupon, Pinterest, Quora, Usabilla and WePay.
However, with Phabricator’s support discontinued, the majority of these companies moved off of the tool, such as Khan Academy, which confirmed it had moved to GitHub in 2020. The only companies still using stacked diffs with Phabricator tooling are those which maintain their own Phabricator source, often because an internal infrastructure team owns it. Companies which I know do this:
Uber: one of the earlier adopters of Phabircator and stacked diffs, with a dedicated developer platform team working on Phabricator.
Twitter (now X): uses Phabricator. Some engineers stick to a regular branch-based GitHub-like workflow – which is also possible with this tool. However, many engineers use a Twitter-internal tool called “multidiff” for a stacked main branch workflow.
Rubrik: also supporting its own Phabricator version.
Companies using Gerrit have also utilized the concept of stacking because it comes pretty much out of the box. Gerrit is a free, open source code review tool that integrates with Git. Companies where some teams use Gerrit and stacking, include:
Adevinta: a classifieds company which bought eBay’s classifieds division in 2020. Some teams use Gerrit, and some others utilize Maiao, a Gerrit-like workflow for GitHub that Adevinta built and open sourced
Wikimedia uses Gerrit, together with a neat project to facilitate creating and updating stacked merge requests on GitLab
Amazon: some teams use it
Arm: a couple of teams use this tool
… and likely many more!
In the comments, Jeffrey Altman shared details on how OpenAFS (a distributed filesystem project) and AuriStor (a global namespace file system) has used a workflow akin to stacking, although not called this:
“These projects migrated to Git/Gerrit in July 2009. In the OpenAFS developer community we required:
1. One change per patch and one patch per change
2. Changes should be small enough to be reviewable while waiting for a bus
3. Every Change must pass continuous integration testing
4. A Change-Set (or Gerrit Topic) consists of a stack of dependent changes
OpenAFS operates Gerrit in rebase mode. Merge commits are avoided (with the exception of security fixes which are developed outside of the public repository.
The benefits of small reviewable changes are ease of review; ease of back-porting; and more precise identification of the point of failure when bisecting.”
Companies that are customers of Graphite, given Graphite builds stacking on top of GitHub workflows. These include:
Chronosphere: an observability company where we covered their story, recently
The Browser Company: they build the innovative Arc browser
Vercel, DuckDuckGo, Ramp
Teams using Sapling or ReviewStack. Both Sapling and ReviewStack are tools open sourced by Meta. Sapling is a source control system that integrates with Git and provides convenient methods for stacking. ReviewStack is a user interface for GitHub pull requests, adding support for stacked changes.
Why is stacking not widespread outside Big Tech?
Why is stacking not more popular? Given its productivity benefits and that Google and Meta both use it at the core of their workflows, it’s surprising this practice remains obscure. Having asked around and personally considered this question, here are the biggest reasons why stacking is not widespread:
Lack of tooling. The primary reason is that a workflow and tooling are needed which support stacking. Google built this in-house, as did Meta with Phabricator, while Gerrit has support for it. However, unless you adopt Gerrit, or have an infra team the size of Google’s or Meta’s to build it from scratch, or a developer platform team like Uber and Twitter/X has to support a Phabricator fork, then you simply won’t have this kind of tooling
“Gated” knowledge. “These tools are gated and so is knowledge of the practices themselves! There's no readily-available way for smaller companies to leverage stacking, so there’s a good chance that they haven’t even heard of the practice,” – Jacob Gold, founding engineer at Graphite.
It’s a relatively new concept. “It wasn’t really widespread at Facebook until 2016. We literally built Graphite because we were disappointed by the lack of tooling publicly available to support stacking. The fact we built an entire company on top of this concept shows how hard it is to build tooling for this workflow from the ground up.” – Nick Yan, software engineer at Graphite.
It’s complicated. “The stacked diffs workflow is relatively complicated. I think a lot of engineers don’t have the patience, and/or the git skills, to make it worth the overhead.” – Shawn Burke, distinguished engineer at SoFi, and former principal engineer at Uber.
5. Meta’s other neat developer tools
I asked all five former Meta engineers who contributed to this article – Tomas Reimers, Aryaman Naik, Jacob Gold, Brendan Ngo, and Nick Yan – which internal developer tools they liked using at Meta. These tools are mostly unavailable outside of the company:
Unidash: create custom dashboards with any data. Heavily used for monitoring.
Scuba: a tool to create analytics tables and query them via a graphical user interface (GUI.) This GUI was composable with Unidash. Scuba is used both for monitoring and analytics use cases.
On-demand: spin up a machine with a clone of the monorepo and develop instantly. It is a kind of cloud development environment. We cover CDEs in the article, Cloud development environments.
QE2 is a tool used for feature flagging and feature gating. It is heavily used across the company. A third-party tool that offers similar functionality is Statsig.
Workplace is a “Facebook, but in a work context,” including profiles of all employees, status updates, groups, search, etc. Workplace is now a standalone Meta product and available for companies to onboard to.
Workchat is a chat and group chats product. Think of it as a “Messenger for work,” or a Slack alternative.
Phabricator helps with the organizing and displaying of diffs, and the tool that had support for developer workflow actions, like creating a pull request (a diff), or merging it back to main (landing a diff). Phabricator is the tool which inspired Graphite’s founders.
ButterflyBot allows engineers to define various rulesets for adding reviewers to specific PRs. For example, you could create a rule that if a PR contains some keywords, or if it is changing specific parts of code, then you’d like a rule to fire. You can also do neat things like associate diffs with tasks. ButterflyBot also sends notifications across Workchat and email.
Task Reaper is a clever tool, built to automatically delete tasks previously created by engineers or managers. You can define a ruleset, such as “delete tasks created by anyone on my team, which were not updated for 6 months or longer.”
Buck is a super-fast, multi-language build system. It is open sourced and used outside of Meta. It’s now called Buck2.
Brendan described what using the tools above was like:
“What made these tools so magical at Facebook was how integrated they were. They all communicated seamlessly with one another and worked as one unit to power your workflow.
In the real world, dev tools feel extremely fragmented. Companies generally use SaaS products in the tens – sometimes, even hundreds! It’s little wonder so many different tools working together doesn’t always feel very integrated.”
We cover Meta’s internal tools in the article, Inside Facebook’s engineering culture.
6. The impact of Meta’s dev tools on the industry
Graphite was born thanks to inspiration its cofounders took from Meta’s internal developer tools – specifically, the stacked diffs flow. I asked cofounder Tomas Reimers what impact he thinks Meta’s internal tools have on the industry. His take:
“Most developer productivity companies usually start by borrowing concepts used by internal tools at a large company. I can point to several tools that were inspired by Meta’s approaches, and founded by Meta/Facebook alumni:
Asana: work management. The company was cofounded in 2008 by former Facebook engineers Dustin Moskovitz and Justin Rosenstein. At Facebook, the pair built the task management tool, Tasks.
Threads: a Slack replacement, cofounded in 2017 by Meta alumni Rousseau Kazi and Jon McCord. Not to be confused Meta’s own Threads social network product, launched in 2023.
Statsig: feature management and experimentation platform. Vijaye Raji founded the company in 2021 after 10 years at Facebook.
Expo: create universal native apps with React that run on Android, iOS, and the web. Cofounded in 2016 by Facebook alumni, Charlie Cheever and James Ide.
Kintaba: an incident management platform cofounded in 2020 by John Egan, Zac Morris and Cole Potrocky, who all previously worked at Facebook.
… and the list goes on!
Entire companies have been created around these tools, and have raised billions of dollars of total funding. It’s pretty strong evidence that Meta’s dev tools have a large impact on the wider tech industry. So why are these tools not more widespread?”
Jacob Gold, founding engineering at Graphite, said it’s due to the cost of development and support, as well as the obvious pain point of fragmentation between tools,
“Tooling for stacking is complex (i.e. expensive) to develop and support. Facebook has hundreds to thousands of engineers constantly working on development and upkeep of internal workflows and processes; I mean, they maintain their own language, Hack!
It takes a pretty big bet to dive into replicating these tools, which is one Graphite is undertaking right now. It comes down to how we believe in this tooling and workflow, and have the conviction that there’s enough engineers out there who would fall in love with this way of working as much as we did.“
My take is that fragmentation and the cost of developing this tooling are two important reasons why stacking is not widespread:
The pain point which stacking solves is obvious only on large teams. For small teams, there’s not a huge difference between using pull requests or utilizing stacking. This is especially true when engineers rarely step on each other’s toes.
Stacking is not straightforward to adopt today. The elephant in the room is that it’s hard to adopt a workflow if GitHub doesn’t natively support it. GitHub doesn’t support the concept of stacking, meaning that teams which want to use it need to use an additional tool that has this, such as Gerrit, Maiao, Graphite, or similar, or build their own.
7. Working at Meta versus working at a startup
It’s rare to get to talk to five software engineers who’ve all worked at Meta, and who now work together at the startup, Graphite. Obviously, I had a few questions about the experience, so far:
There’s a popular belief that Meta runs teams like they’re startups. How true is this, now you really do run your own startup?
Jacob Gold:
“Is that really a commonly-held belief? I’m not sure I agree. Maybe a few pockets of the company move as fast as startups, but being at a startup still feels completely different.
At real early-stage startups you just learn so much faster than in a more established corporate setting. You also just have so much more immediate control over the implementation and direction of the product. And this is coming from someone who worked for some time at Meta!”
The most transferable skill from Meta to a startup
What skills did you develop at Meta which helped you hit the ground running at Graphite?
Nick Yan:
“Iterating quickly. This was the most important lesson I took from my time at Meta. Whether we were building a proof of concept, or trying to figure out how some new functionality would fit into our existing codebase, prototyping out quickly was super helpful.
Iterating fast also helped during disagreements with teammates and leadership. ‘Code wins arguments’ is a cultural value at Meta which we used a lot. It’s a lot easier to argue against something theoretically than when you can see the code itself in front of your face, and that code speeds up rendering times by 10x!”
Aryaman Naik:
“Get stuff quickly into the hands of real users. This solves pretty much all your problems! Shipping a first version fast, and then shipping incremental fixes in a speedy fashion is much better than having something sit in ‘QA hell’ for years! By ‘QA hell,’ I am referring to the QA team saying a version isn’t ready to ship due to a very long list of issues, then the developer team fixing these issues, and then this cycle repeating several times, until the QA team finally gives a greenlight to ship to users.
I’m not saying you want users to find ALL the bugs! And of course you want to release a reasonably polished product. But no matter what you do, you will never be able to test every edge case before launch. And that’s okay!”
Adjusting to the world of startups after leaving Meta
What did you need to “unlearn” from your time at Meta?
Nick Yan:
“Starting a codebase from scratch was an unexpectedly strange experience! At Meta, you get used to working with this massive monorepo; whenever you start a new project, you have this massive internal codebase to take inspiration from. Meta is such a huge and mature product that they already solved a lot of challenges you’ll face, so you can expand on those approaches, and get inspired by how you did it.
When we started Graphite, we had no existing codebase to lean on. At Graphite, we had to learn to open source solutions for inspiration, and to rely on ourselves to build from scratch because there was nothing comparable available. Especially in the early days, I missed being able to just ping for help from another team at Meta which had solved problems like the ones we faced!”
Brendan Ngo:
“We needed to ‘unlearn’ how stuff just works! At Facebook, everything is kind of just handed to you! What I mean by this is even when you start a new project, you have CI/CD pretty much taken care of; linting; feature flagging; release practices and every other common thing you can think of: you don’t need to worry about it! And if something doesn’t work, you can ask for help from infra teams and they’ll sort it for you.
At a startup, you are forced to be a lot more creative, and learn much quicker. This is not a bad thing, but it was a different reality from what we were used to at Meta. At a startup like Graphite, when as an engineer you have a problem, it is YOUR problem. There is no dedicated team that owns a module you are using, or the service you want to modify because this small startup team owns everything! It’s up to you to solve your problem.”
Takeaways
Ever since leaving Uber, I’ve wondered why stacked diffs are rarely used across the industry. I had the benefit of first-hand experience of just how powerful this workflow is, and every single Meta engineer I talked with thought the same, as did many Google engineers.
Today, more companies are exploring moving to a stacked workflow, overwhelmingly driven by Google or Meta alumni advocating the usefulness of this approach. I recently got wind that Databricks is considering adding tooling support for this feature.
I hope today’s issue explains this workflow and its benefits, especially for large engineering teams that merge to the main branch. It’s rare to come across a helpful engineering practice with such a low profile across the broader industry.
Special thanks to the five former Meta engineers now building Graphite, who contributed to this article. For further reading, I recommend these articles:
Stacked diffs: a Twitter thread by Benjamin Schachter (2022)
Problems with pull requests and how to fix them by Gregory Szorc (2020)
Stacked diffs versus pull requests by Jackson Gabard (2018)
Stacked diffs: Keeping Phabticator diffs small by Kurtis Nusbaum (2016)
I'm not sure if I fully understood what is different or novel about stacking/chaining. I've only ever worked at various small startups, with regular Git/Github or other version control. But all of the following was always true:
- We submitted multiple small PRs for a feature/ticket instead of one big PR
- We started the next PR without waiting for reviews on the previous one
- We rebased multiple times a day
It's natural to end up working this way as you streamline your workflow, and most tooling supports this without hiccups. For example, GitHub lets you set the base of your new PR to your previous PR so you can see changes in separation, and it will seamlessly update when the base PR gets merged to main.
Aren't stacking and chaining just custom terms for a common industry practice, used for custom tooling in Big Tech?
Thanks for putting this together, Gergely! I've coached many engineers on stacking over the years. It still astounds me that breaking up PRs into reviewable parts isn't something directly built into Github. In any team with robust code review practices, pretty much every junior or even mid level engineer goes through the gauntlet of posting a massive PR only to be asked by reviewers to break it up. Even senior engineers get caught out by this.
Solving this problem at scale would be hugely valuable.