Don't forget the silent step when you squash and merge

I usually follow thoughtbot’s git protocol when introducing new code into master, where we rebase interactively (to rebase and squash commits) and then we merge. But when I don’t use that, I really like GitHub’s squash and merge button.

But too often, I find that people who use that button tend to miss the middle step (I might even call it the silent step) between squashing and merging. They usually click “Squash and merge” and then immediately hit “Confirm squash and merge”,

In doing so, they forget to write a good cohesive commit message! So what I’ll find is commit messages that look like this one,

Author: Developer <dev@squashandmerge.com>
Date: Thurs Dec 20 00:00:00 2018 --0400

  Add users to the checkout flow

  * wip: original implementation

  * add new routing for guests

  * hound updates

  * styling changes

  * fixed css nesting

  * change color for primary action

  * whoops, removed inspects

  * address feedback

  * hound again!

  * pass tests

The commit message above does not tell the reader what changes were introduced or why they were introduced. It is simply a series of work-in-progress commits that were done at a point in time. There might be a commit in there that provides helpful information, but usually there is so much noise that it is hard to find it. And the reader is left to guess at the reason behind them.

This is a crucial opportunity missed! With a good commit message, the author could have communicated the reason behind the changes across space and time!

Wouldn’t it be better if you found this?

Author: Developer <dev@squashandmerge.com>
Date: Thurs Dec 20 00:00:00 2018 --0400

  Add users to the checkout flow

  Trello: https://trello.com/z/aYaZaAAa/59-users-checkout-flow

  What changed?
  ======================

  This commit adds users to the checkout flow. In order to do that we had to
  add new routing for guests since our current implementation did not
  account for them.

  We also updated the colors of primary action buttons to better match the
  checkout flow.

  Why are we doing this?
  =====================

  We are introducing users to the checkout flow so that our customers can
  store items and come back to their shopping cart later. The actual work of
  persisting the shopping cart is not done here, but this lays the
  groundwork for all that future work.

Write a cohesive commit message

So next time you hit the “Squash and merge” button, take a breather, and use the text box conveniently located on top of the button to write a nice cohesive commit message before you “Confirm squash and merge”, changing something like this

into something like this,

That is much better. Now you’re ready to “Confirm squash and merge”!