Stacked changes implement and review a complex change as a series of smaller feature branches that build on top of each other. Benefits of stacked changes are:
- developer and reviewer maintain momentum and block less on each other
- breaking up the problem of developing/reviewing a complex problem into developing/reviewing many smaller problems
- minimize merge conflicts by shipping parts of a complex change that are already approved separately from parts still under review
The single responsibility principle applies to feature branches the same way it applies to functions, classes, and methods. Feature branches should also perform only one change. Implementing, refactoring, reviewing, and resolving merge conflicts on such single-responsibility branches is easier than with branches that combine unrelated changes.
Git Town supports stacked changes naturally as part of its bigger picture about branch ancestry.
Let's say we want to add a new feature to an existing codebase. Before we can do that cleanly, we need to get the code base ready:
- Make the architecture more flexible so that we can add the new feature in a clean way.
- Clean up some technical drift: improve the names of variables and functions.
- Build the feature on top of this modernized codebase
Implementing all these changes in a single feature branch is risky. Some changes like the refactor in (1) touch a lot of files that other people might change as well. We want to review and merge them as fast as possible to minimize merge conflicts. Other changes like building the actual feature in (3) will take a while to build. We should therefore make both changes in separate branches. At the same time, the feature (3) depends on the changes in (1) and (2) and drives the changes in (2). We want to develop these changes together. The solution is a stack of feature branches.
The first feature branch contains the refactor. We create a feature branch named
1-refactor off the main branch to contain it.
git hack 1-refactor
git hack creates a new feature branch off the main branch. We perform the refactor and commit it.
With the refactored architecture in place, we can update the names of some
variables, functions, and files whose role has changed as the code base has
evolved. Since these changes require the refactor, we perform them on top of
git append 2-rename-foo
git append creates a new feature branch on top of the
currently checked out branch (which is
1-refactor). We now have this lineage:
2-rename-foo builds on top of
1-refactor and thereby contains all the
changes made there. We commit the changes that rename the
Because we used
git append to create the new branch, Git Town knows about the
lineage and creates the proposal (aka pull request) for branch
1-refactor. This way, the proposal for branch
shows only the changes made in that branch (renaming the variable) and not the
refactor made in branch 1.
This is a different change from renaming
foo and has different reviewers.
Let's perform it in a different branch. Some of these changes might happen on
the same lines on which we also renamed
foo earlier. We don't want to deal
with merge conflicts coming from that. So let's make this change on top of the
change we made in step 2:
git append 3-rename-bar
The lineage is now:
bar, we discover another improvement for the architecture.
Let's add it to the refactoring branch.
git checkout 1-refactor
# make the changes and commit them
git checkout 3-rename-bar
Back on branch
3-rename-bar, the additional refactor we just added isn't
visible because the commit for it exists only in branch
1-refactor right now.
Let's propagate these changes through the entire branch chain so that they
become visible in branches 2 and 3 as well:
Because we created the branches with
git append, Git Town knows about the
branch lineage and git sync can update all branches in the
right order. It updates the
main branch, merges
main into branch 1. Then it
merges branch 1 into branch 2 and branch 2 into branch 3.
We got the approval for the refactor from step 1. Let’s ship it!
git ship 1-refactor
You have to use the git ship command here because it updates
the lineage that Git Town keeps track of. With branch
1-refactor shipped, our
lineage now looks like this:
We have been at it for a while. Other developers on the team have made changes
to the codebase as well. We don't want our branches to deviate too much from the
main branch since that leads to more severe merge conflicts later. Let's get
all our branches in sync with the rest of the world!
git sync --all
This pulls updates for the
main branch, then merges it into
We can now add the new feature on top of the code base we prepared:
git append 4-add-feature
Let’s stop here and review what we have done.
- Each change happens in its own feature branch.
- Our feature branches build on top of each other and see changes in their parent branches.
- We review and ship each feature branch in the chain in isolation.
git hackcreates a feature branch as a child of the main branch.
git appendcreates a feature branch as a child of the current feature branch.
git synckeeps a feature branch chain up to date with the rest of the world
git shipships the oldest feature branch in a branch chain.
Single-responsibility branches are easier to reason about and faster to implement, debug, review, and ship than branches performing multiple changes. They encounter fewer and smaller merge conflicts which are easier to resolve than merge conflicts on branches that implement many different changes. You can review and ship parts of your complex change before the entire change is finished. You can still make different changes in parallel, just commit them to the correct branch.
Branch discipline: when you have an idea that is different from what you currently work on, resist the urge to code it in the current feature branch. Implement it in its own feature, parent, or child branch.
Keep the entire branch chain in sync: Make sure you run
git sync --all or
git sync on the youngest child branch to keep the entire chain of feature
Avoid unnecessary chaining: If your feature branches don't depend on each other, put them in (independent) top-level feature branches. This way you can ship them in any order.
Organize branch chains in the order you want to ship: You always have to ship the oldest branch first. You can use git prepend to insert a feature branch as a parent of the current feature branch or set parent to change the order of branches.