Git Better #1 — Commit Message Convention

Many of us don't pay much attention to commit messages. But when we need to look for a specific change, or we are wondering why an addition was made, problems appear. What if I told you, there is a simple and easy way to greatly improve the experience with git history.

Troubling Reality

Let's be honest, we all have seen (and been a part of) such git logs:

ad8621a Fix a bug in the feature
16b36c6 Addressed a PR comment
23ad9ad You can now download form correctly through the main website
21672sd Typing for mypy

These messages try to describe what changes have been made, but ultimately are not much of use. Why?

No Location

They don't point to the place in the code where the change was made.

No Type

They don't specify what type of change was made, making it impossible to filter.

Inconsistent Style

Each one is written in a different style — no pattern, no structure.

All of these problems may be solved by adopting a git commit message convention into the project, and today I am going to show you one — Karma.

What Is Karma?

Today, we are not talking about famous religious-based "you get what you do". However, that analogy is quite fitting as karma will sooner or later get you, if you are not using proper commit messages.

The Karma I want to show you is a git commit message convention, birthed from the AngularJS Git Commit Conventions google document, adapted to be used with any project and language. It aims to provide more useful, clear and precise information when browsing the git history, while also helping to easily achieve other goals:

Automatically generate changelog — When your git messages follow a convention, it is much easier to generate a changelog:

git log <last tag> HEAD --pretty=format:%s
# All commits since the last release

23ad9ad feat(proxy): Added support for bi-directional streams
21672sd fix(proto): Fixed missing type annotation

Filter out unimportant commits — Using unified descriptions we can easily look through the history and pick only the interesting ones:

git log <last release> HEAD --grep feat
# All new features since the last release

23ad9ad feat(proxy): Added support for bi-directional streams

How to Use It?

The general structure of a Karma based message is:

<type>(<scope>): <subject>

<body>

<footer>

It is really simple to remember and once you start using it, you will almost never have to consult the reference. Each line can have a maximum of 80 characters and the second line must always be blank.

Allowed Types

feat

New features, or ones that changed behaviour.

fix

Bug fixes in ready features.

docs

Documentation, both in and outside code.

style

Formatting, typos — no code change.

refactor

Refactoring production code.

test

All things test related.

Scope

The scope is a description of what part of the code was affected — for example: service, proxy, runner, etc.

Body & Footer

In the body, include a sentence on why the changes were made. Be descriptive! If someone looked this far inside your commit, they will appreciate every bit of information they can find.

In the footer, you can reference issues. Multiple issues may be used at the same time.

Full Example

fix(service): Verify the content type that is returned to the adapter

API can respond with text/plain content type instead of JSON.
To ensure proper operation it is verified before further processing.

Closes #112

Further and more precise explanations can be found on the official Karma website, which I highly recommend as a reference.

Why Should I Bother If I Never Use Git Log?

You may say: "What you wrote looks nice, but I honestly can't remember the last time I actually used git log." And I have to agree — during everyday work it rarely happens that we need to use git log extensively. Here are some additional thoughts:

Like Backup

Good commit messages are like backup — you think you don't need one until you do.

Fully Customizable

As long as you state the rules and stick to them, it will be beneficial. Even just the first line of Karma is enough in most scenarios.

Handover-Ready

Think about a situation where you take over a project. Which kind of commit messages would you prefer? Maintain your project so you're not ashamed when someone else reads it.

Better History = More Usage

Maybe you would be using your git history more if it was better structured, not the other way around.

Convention Levels

minimal    fix(service): Verify the content type returned to the adapter

ambitious  API can respond with text/plain content type instead of JSON.
           To ensure proper operation it is verified before further processing.

full       Fixes #112

Closing Off

If you are convinced, share the idea with your team and try sticking to Karma rules for your next project. You can also convert to the convention in an ongoing one. Changing git messages will rarely break anything in your environment, so it doesn't hurt to try — it is never too late to Git Better.

This article is a part of the ongoing series "Git Better with MusicTech Lab". In the next one, we are gonna cover cherry-picking — when it is a good practice and how to avoid common errors using it.