Squash merges
Martijn van Steenbergen
LessonUp
September 2024
Squash merges
Martijn van Steenbergen
LessonUp
September 2024
Development process
We can think about:
Release process — "Why do we have a main branch?"
Duorepo — "I forgot to git-pull lessonup-2.0"
Squash merges — "Where did this breakage come from?"
Test quality — "The tests didn't catch my bug"
Code ownership — "Bee-team broke my editor!"
Code reviews — "Why is no one picking up my PR?"
Build dependencies — "I forgot to run pnpm install"
Today we will focus on squash merges.
Today
Current situation
Proposed change
Pros and cons
Discussion
Current situation
Multiple commits per PR
Every commit becomes part of history
History of the develop branch is nonlinear
Pain points
The branching structure is hard to understand
Many commits are noise. Examples:
Merge branch 'develop' into...
ED-970/new function name
BEE-514/fix build
ED-980/cleanup
BEE-545/Formatting the test correctly
Repetition between commit messages and PR contents
Extra work to create a commit discourages code snapshotting
Units of change vs units of review
The PR is the unit of review: a cohesive set of changes you ask someone else to review, and then merge into develop in one go.
When looking back in time, here are two units of change:
The PR as a whole: title, description, etc
Individual commits, on a smaller scale
Insight: individual commits are useful during development as "snapshots" of work in progress, but lose their value after merging.
Proposed change
unit of change == unit of review
Append the whole PR as a single commit to develop.
While the PR is in development, keep all commits (just like now).
When merging the PR:
Combine all commits
Use the PR title and description as commit message
Append the squashed commit onto the end of the develop branch
Remove the PR branch
GitHub has native support for this. ✅
PR
Effects (1)
History of develop becomes linear
Every commit message in develop is meaningful
Easier to find the source of changes
Branches live only as long as their PR
Effects (2)
Commits during development become completely irrelevant except as a snapshotting tool for the author
There is increased focus on high-quality PR titles and descriptions
Reviewer is empowered to contribute to quality
We are free to move any precommit logic to the PR level (e.g. requiring a reference to the Jira ticket)
Things that stay the same
Review process is unchanged
Requires no changes to release process
Still easy to generate changelogs
Commits link to tickets and back
(but tooling might need to be updated)
Caveats
Developers need to get used to putting effort in PR descriptions, away from commit messages
PRs that do multiple unrelated things become more painful
Your local copy of the feature branch sticks around
Checklists in the PR descriptions become part of the commit message
Branching off of a pending PR becomes a bit more painful
Alternatives
Rebasing: keep every commit, and append all PR commits to develop.
Removes all branching points and also achieves a linear history.
Also supported by GitHub
Maintains the ambiguity between unit of change and unit of review.
Squash merges, but combine all commit messages
Keeps a semblance of the ambiguity of unit of change
Repeated work between commit messages and PR description
Implementation
Set expectations with the dev team
Perhaps write a ½-pager to explain
Prepare tooling
Set the default squash merge message to PR title + description
Make squash merge the default for PRs
Announce when the changes are live
Recommended:
Remove mandatory git commit hooks
Move these checks to the PR level (e.g. through GitHub checks)
Also consider:
Use branch protection to only allow squash-merged PRs to update develop
Questions? Thoughts?