The Evolutions of Git Commit Message Conventions in Kurio

We in Kurio use Github as our version control system. And because of that, we also have a flow like open source project does.

For example, when someone developing a new feature, or just fixing some bugs they must create a pull request to main branch. Then everyone that is responsible (their team’s member) review the submitted PR.

If it passes, then they will merge it to main branch and will be responsible to deploy it into staging and release it to production.

Code Review

And then, one thing we must really concern is about the git commit message. We have the unwritten rules here about git commit messages, it must be clear and understandable.

Well, we have a long journey to come to this day until our git commit messages look clear and clean.

1. Start From Just a Simple Explanation

Well, everyone starts from here. When doing commit we just put as is, what we’re doing or fixing.

For example, if someone fixing a bug, they should explain in their commit message. Like example below.

$ git commit -m "Fixing logic of something"
$ git commit -m "Add new features of something"

Well, we stick with this kind of conventions for a long time. If we look at the git commit history it will more look like this.

Kurio git commit history

It’s not well structured. Also, it’s a boring thing when reading this kind of git commit history.

2. Introducing Emoji

And then a few months later, around December 2017 (I read from our git commit history). I remember I proposed a new unique git commit message conventions to our team in Backend at Kurio :D.

I proposed this after I found this repository in GitHub: https://github.com/dannyfritz/commit-message-emoji, instead of a normal commit message, he introduced a commit message with emoji.

Commit emoji from https://github.com/dannyfritz/commit-message-emoji

Well, when doing this, it’s a fun thing. I like how the conventions work. Our commit message looks colorful, and fun :D.

A few of us also agreed with this kind of git commit conventions :D. So a few of us at the backend team use emoji when committing changes to our projects.

Commit with emoji at Kurio

And that happens just for a few months. Well, it’s fun, but something is missing with this kind of commit message. It can lead to confusion when anything happens in deployment and we want to revert to a specific commit. Too many distractions in commit message when we want to read the commit history.

So later, a few months later, we starting to leave this kind of git commit conventions. And back to the previous one, with just a simple explanation of our git commit message.

3. AngularJS Styles

But, later, we found a new good thing. These conventions used by many open-source contributors in Github. This git commit message convention is introduced by the AngularJS team.

They even put it into a Google doc about their git commit conventions here: AngularJS Git Commit Msg Convention

AngularJS git commits message conventions.

These conventions are looked more clear and clean. And after a few months, we try to implement this. Even it still not look perfect like the AngularJS team do, at least we use the term at our commit messages.

To do this is not happen in a night, we move to these conventions slowly. It’s not easy to convince everyone and change the habits of the engineers. Forcing will bring chaos :D.

So, our team making this kind of commit message slowly and spreading to all of our repositories. (Anyway, I’m one of the engineers that a bit hard to move to this kind of conventions :D). But later, after I look at the result, now I agree that this convention is better.

The commit message looks structured and clean. This how our commit messages looks now.

Kurio git commit message

It took a few years until we agreed on this git commit conventions. Some people may not take this seriously, but this is very important things.

I have an experience that must force me to look to our git commit messages that not structured well. I don’t remember when it happens, but it happens when we have a bug in production, that already running for a month, since it’s released. And this happened when we just put a simple explanation on our git commit messages (the evolution version 1 above)

To debug this, we look to our git commit histories, which commit caused this bug. Since it happens a month ago, there are already many commit messages merged to production branch. And the history is not structured as we used now.

So to tracing the changes, we look for each commit messages. Even we know it happens in a feature(feed-feature) but we don’t know which PR/commit that caused this bug. It really messy, and confusing.

But, it’s different now. Now our commit message already structured and clean (not 100%) but we still trying to make this better and better.

4. What’s Next?

For now, we just follow how the commit message conventions that introduced by AngularJS. There is a reason why we choose this convention.

This convention will really help to do the semantic-release, as we know, some people can really hard to do the semantic-versioning. And sometimes, some people too lazy to make a clear release notes.

With the commit message like this, we can easily to decide what will our next version number of our application, there will be no more sentimental-versioning, it will force us to be strict and follow how the semantic-versioning works.

For example, let’s say we have an application that already versioned v1.0.0, let’s called it TODO application. Then, for example, we add a few changes, that’s to add a print log to each error condition, so we can see the logs when errors happen in production.

This changes, need a lot of energy because there is so many error condition in our application. It may take a week to add the logger. There will be countless commit message if it was very complex system.

And then, imagine that when doing that, every engineer that contribute to adding the error don’t have any commit message conventions, they use their own styles.

And when it finished, someone that in charge to release a new version of the application will be really confused. Should he release a major, minor or just a patch?

A clear and structured commit message will really helpful to decide what will our next version number. If we found like feat that means a minor, or when we found a chore that will be just a patch versions that really don’t affect any production or when found something breaking then it means it was a new major version that may have totally different changes compared to previous versions.

And also with this commit conventions, we can clearly write our release notes based on our commit history, it’s clean and structured anyway, so we can easily to write what would be our release notes checklist.

This is also the reasons, why AngularJS use this convention, so they can automate their release flow with ease.

*ps: Luckily, there is a tool that already used by many companies here: github.com/semantic-release/semantic-release, this tool will help us to decide the next version number, generate the release-notes, as long as we follow how the git commit conventions that they agreed

Originally posted at Kurio Engineering Blog: https://toolbox.kurio.co.id/the-evolutions-of-git-commit-message-conventions-in-kurio-4a03b441d06a