STACKING WORKFLOW
Why stack
Stacking enables you to break up a large engineering task into a series of small, incremental code changes, each of which can be tested, reviewed, and merged independently while staying unblocked. A stack is a sequence of dependent code changes, each building off of their parent.
tweets
What other people are saying?
01.
Stacked changes are just multiple dependent PRs. Stacking keeps authors unblocked while waiting for review, evokes higher-quality review comments, and lands small changes faster. Reviewers get bite-sized changes, spend less time re-reviewing, and have more granularity to bisect and rollback if something goes wrong.
People tend to avoid stacking because of the pain that comes with maintaining and merging a stack. Each time a base PR changes, there's a need to ârestackâ (propagate down-stack changes upward via recursive rebasing) - this is where tooling can help.
Many of the largest companies see the benefits of stacking code changes and have built internal code review platforms to help merge and restack, such as Critique (Google) & Phabricator (Facebook, Dropbox, Uber, Pinterest, Quora, Twitter).
Stacking and features branches both enable trunk-based development. The critical difference between stacking and feature branches is that stacked PRs donât need to directly branch off of main; they can instead branch off of each other. While a feature branch can become bloated and hard to review, a stack can always stay light and modular. Feature branches need to be reviewed, pass CI, and merged as one large chunk. Stacks can be reviewed in small pieces, pass CI one branch at a time, and be merged in whenever ready.
02.
If you have ever branched off of a branch and opened two, dependent PRs, you have already stacked. This workflow is natively supported by git, and just requires that you checkout and start working on the parent PR, rather than always developing against main.
Some developers prefer to write a large change first and then split it into a stack of smaller changes later. This can be helpful when youâre unsure of the final code structure upfront, but still want to submit a sequence of small, independently-reviewable changes.
03.
Updating stacked branches is no different than updating traditional branches. The only difference is once you update a stacked branch, youâll need to update the merge base of any dependent PRs too. If rebasing after every change is a daunting concept, have no fear; this is a place where tooling can automate.
04.
When youâre ready for review, you can create a PR per branch in your stack. You can open your first PR the moment you stack on your second branch. Frequently submitting changes will ensure that the pull requests remain small and easily reviewable for your teammates.
Small PRs allow you to be more selective with requested reviewers, which reduces the bystander effect and notification spam. And since the pull requests are smaller, reviewers have to do less context switching. They know exactly what theyâre looking at and can more easily give feedback.
If reviewers request changes, you can update your pull requests independently without needing to update the rest of your stack.
Once your changed are approved and passing CI, youâre ready to merge. Stacked changes always merge into trunk, meaning you always merge your stack bottoms up. Once a PR is merged, the base branch of the dependent PRs need to be updated to point to trunk - another opportunity for automated tooling to help.
How Graphite helps you stack
Much of the process above can be automated by tooling. For example, Graphite can help:
Visualizing
Graphite creates a visualization of your stack in the terminal, on our web dashboard, and as a GitHub comment, so that you always know where you are.
Merging
Graphite can merge many PRs in a stack at once using our merge-all functionality. That merges your PRs in order, for you.
Automatic rebasing
When you update a PR in a stack, Graphite automatically rebases all up-stack (dependent) PRs for you; intelligently applying any rebase conflicts you resolve so that you only have to resolve them once.