Squash merges

Squash merges

Martijn van Steenbergen

LessonUp


September 2024

1 / 14
volgende
Slide 1: Slide
newEditorSoftwareontwikkelingBeroepsopleiding

In deze les zitten 14 slides, met tekstslides.

time-iconLesduur is: 20 min
Dit is niet oké

Onderdelen in deze les

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

  1. Current situation

  2. Proposed change

  3. Pros and cons

  4. 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:

  1. Combine all commits

  2. Use the PR title and description as commit message

  3. Append the squashed commit onto the end of the develop branch

  4. 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?