DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Cover image for Being intentional with commits
Erin Bush
Erin Bush

Posted on • Updated on

Being intentional with commits

The other day I was poking around in a github repository and came across this commit message:

a commit message that just says "completed"

Not that I needed to know that much about what this person was committing at the time, but I couldn’t help but think how unhelpful this commit message would be if someone needed to understand the project.

I have also been guilty of creating less-than-descriptive commit messages - I'm sure we've all been there. If you want to see some truly hilarious commit messages you can check out whatthecommit.com.

At my work we started using Commitizen which is based on Conventional Commits specification. It took a minute to get used to but after a few days, I could see how much value it was adding to the code base.

Breaking down commit size

Because it breaks commits down into categories, it forces you to only add relevant files to one category.

Buh-bye editing 30 files and committing them all in one go. I mean, you still could do that but you will feel a slight pang of guilt every time you add a feature change in with your test changes.

a screenshot of the commitizen command line tool

After using the tool for a few days, I started thinking about good stopping points in my work where I could commit - with the intention that I could make my messages make the most sense. For example, when working on a feature that also included some refactor work, I would try to just do the refactor first, commit that, and then start working on the new functionality. Looking back at the commit messages when browsing files and seeing the type of change that was made, helps so much for granularity and for knowing what to expect from a certain commit.

More descriptive messages

While other people on the internet might have already been splitting their commit messages into subjects and bodies, I was not. I’ve now realized, the longer description in the body is so helpful for describing the nuances of the changes you have made. Even if its just for you to go over before you make your pull request, it will help you understand why you did what you in a way more thorough way - provided you actually add a thorough description.

an example of a commit with a message subject and longer description

At my work, we’ve gone a step further to create a custom command line tool that makes your pull requests for you on Github with the pull request description being a list of your git commits. At first, I was worried this wasn’t enough. How could 100 character commit messages tell you everything you need to know about the code changes? But then, I had a lightbulb moment: the commits already ARE supposed to tell you everything about the code changes. I just wasn’t making my commits well enough. Once I started breaking things down by commit category and providing better commit messages (mainly through the longer descriptions), my pull requests were back up to the level they used to be before when I would write the description myself and have subpar commit messages.

I encourage everyone to set up Commitizen and try it out for a few days. I think it will make future you way happier when you are looking back at your code and thinking, β€œWhat the heck was I thinking?”

Top comments (17)

Collapse
geocine profile image
Aivan Monceller

I wrote a tool called golem, something similar inspired by commitizen. I made it in Go, so that I could compile it into a single binary and be able to recommend it to my fellow developers who don't use nodejs.

github.com/geocine/golem

The JIRA ID is optional, can also remove the option totally on the source code.
Golem

Collapse
drawcard profile image
Drawcard

I like this a lot - one suggestion, rename "JIRA issue(s) ID" to something more generic like "Issue(s) ID" to make it adaptable to other issue trackers (eg Github)

Collapse
bycedric profile image
Cedric van Putten • Edited on

Great post! I absolutely love the movement of making commit messages better! 😁 Don't forget to mention that the format Commitizen is using is based on Conventional Commits 😁There are also a lot of tools to do awesome stuff with these commits, like generating changelogs (example of one of my projects) or even "calculate" next semantic version (also example a project of mine).

Here are some of them!

  1. conventional-changelog - Generate changelogs and release notes from a project's commit messages and metadata.
  2. semantic-release - Fully automated version management and package publishing
  3. commitlint - Lint commit messages

Disclaimer; I became one of the maintainers of Commitlint and we joined the Conventional Changelog "group" on GitHub. That basically makes me a CC fanboy I guess πŸ˜…

Collapse
erinbush profile image
Erin Bush Author

Awesome! I'll have to check these out. We use some linting on our commit messages as well and I think its great. Also, I've updated the post to mention Conventional commits πŸ˜„

Collapse
bycedric profile image
Cedric van Putten

Haha nice! Hope most of the developers there are like you and think it's great too 😁 I had to convince some of our developers to stop make "annoyed sounds" and embrace the new standards πŸ˜… Again, awesome article!

Collapse
anotherfoxguy profile image
Edgar • Edited on

I personally use gitmoji-cli for my commits: github.com/carloscuesta/gitmoji-cli

It uses emojis to define the type of commit and makes your repo a lot more colourful

gitmoji-cli

Example of a repo using it: github.com/RigsOfRods/rigs-of-rods

Collapse
erinbush profile image
Erin Bush Author

This is very fun πŸ›

Collapse
mindstormer619 profile image
Siddarth Iyer

One particular commit format I've found which works really well in creating commits with intent is the following:

{Commit message one-liner}

## Motivation

{Couple lines explaining *why* the change is being made.}

## Design

{Couple lines explaining *what* is being done. Not "how",
but "what".}

{Link to a design wiki/document for the change, if any.}

## Misc

{List of links to supporting material, if any. For instance,
a code-review link if you're using an external tool for this.}

An example toy commit message would read like this:

Add splash screen before MainActivity launch

## Motivation

Previously, on app launch, MainActivity would load and display an empty spinner
for up to 1.5 seconds while data was fetched from the server. This was
determined to result in poor UX for the user (see #54).

Therefore, we add a splash screen to display messages to the user while data is
fetched from the server to populate MainActivity.

## Design

We display a splash screen with rotating messages (new message every 2 seconds)
indicating the user to wait while the NetFetcher service gets data from the
server. Splash screen is deactivated on receiving completion event from
NetFetcher.

See Wiki-56 at <link>.

## Misc

+ Code Review: <link>

Tip: Don't create commits like this initially. Commit frequently on your local feature branch as your fancy strikes, and don't be afraid to write minimal descriptions on your messages. However, when the time comes to push your commits up to your main shared branch, rebase your feature commits into one, and write a commit message like this one.

Collapse
qm3ster profile image
Mihail Malo

This is a good template for pull requests, but personally I don't recommend squishing pull requests into one commit.

Collapse
mindstormer619 profile image
Siddarth Iyer

May I know why you recommend not squashing commits for smaller PRs? I can see it shouldn't be done for larger PRs, but for simpler single-feature stuff (which you'd get anyway on frequent integration) setting a single commit would work well. You'd have a relatively cleaner git history and quick reverts if needed as well.

Thread Thread
qm3ster profile image
Mihail Malo

I find it better to have more commits for git-bisect.
Then it ends up being a specific incorrect refactor, which can be made an example of, by adding regression tests, mentioning it in team guidelines, adding lints etc.
When you want to revert the whole merge, you can still use a UI button or git revert -m 1 <merge-commit>.
As for full diffs, it's just as easy to diff two arbitrary points as the state before and after a single commit.
I just don't think it brings anything useful to the table.
Maybe it's appropriate to squash-merge to the release(not master) branch in a non-CD situation. Not sure.

Collapse
rachelsoderberg profile image
Rachel Soderberg • Edited on

A trick I use for even better commit messages is card numbers (something I always do when I have the choice is number my cards in the backlog). I'll write my commit messages like this:
Card #15 - Fixed issue with string concatenation showing null, ShipState set to blank if null before customer is created.

I've found that card numbers allows you to add more robustness to your commit message without being overly wordy. If you REALLY need to research the changes that went on, you have a card number, so you can go reference that for the (hopefully) full breakdown and steps that went into the card.

Collapse
phillipdodd profile image
Phillip Dodd

One might say you're suggesting one really commit to their commits ;)!

Ok, now that the pins out of the way: thanks for sharing this! My team is currently in the process of reworking how we handle our source control and everyone is pretty new to it... the ideas here, in addition to the tool itself, are very helpful to read.

Collapse
levente profile image
Levente

Hi All,
Thanks for this great article Erin!
Good to see this conversation picking up around quality commit messages because my experience is that it's not the favorite topic of developers. At least it's pretty dividing whenever I bring it up. Usually, folks working at a large company in a regulated industry (aviation, healthcare, finance, etc) get it, because they need to comply with a buch of rules.

We work on a Jira app that checks and verifies several aspects of a commit not only at push time but right on your computer at local commit time.

I talked to a developer at Philips whose team is using it. If you are using Jira and interested give this quick interview a read I made with them.

Collapse
seokjeon profile image
Se-ok Jeon

Thx for this! This is really what I wanted. Helped A LOT.
Can I translate in Korean this post? If you don't mind, I wanna share this awesome post in Korean. Surely, There will be a linke directing to this original post.

Collapse
pauguillamon profile image
PauGuillamon

Thank you for making me discover whatthecommit.com!!!

Collapse
darkain profile image
Vincent Milum Jr

Possibly NSFW text..? But this site always gives me a laugh for crazy things people put into commit messages: commitlogsfromlastnight.com/

🌚 Life is too short to browse without dark mode