How to write good commit messages?

The strength of Git is obviously to store and version all the modifications of a source code over time, in order to keep a history and be able to revert to a previous version if needed.

But you can't browse through a history efficiently unless you know what you're browsing through...

Indeed, commit (version) messages are a very important facet of managing a development project!

Each commit can contain a large amount of important info, and it's necessary to find a message structure that:

• is easily understandable
• not too difficult to write
• hierarchizes the information well

Fortunately, there is a convention that checks all the right boxes: conventional commits

Conventional commits

Ideally, a commit message should contain all the information necessary for a human to properly understand it, and therefore:

• The type of change (e.g. a new feature)
• The scope of the change (the part of the code modified, such as a module)
• The description of this change
• The number of the ticket, or "issue" fixed (optional)

And here is the format recommended by this convention:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Which results in a commit example like this one:

fix(user): authenticate user with email instead of username

Issue #132

The specification contains 15 rules to follow precisely, such as commit types: feat, fix, refactor, build, chore, ci, docs, style, test,…

You can find all the information, and the possible values, related to this convention on the dedicated website: https://www.conventionalcommits.org/en/

As a bonus: this convention makes it fairly easy for a machine to parse commit messages, and therefore generate changelogs for example!

A customized variation

Personally, I long used a variant (before knowing the convention above) that is fairly close, slightly more concise, like this:

[TYPE] scope (#issue) - message

Which results in commit messages looking like this:

• [REFACTOR] User (#5) - Merging User and Account models
• [FIX] Notifications (#18) - Emails were not sending due to wrong smtp credentials
• [FEATURE] Post (#65) - Images can be added to posts using the editor

It's still highly recommended to use conventional commits, but you're free to opt for this one instead

Because even a non-standard convention is better than no convention at all (and let's not even talk about commits with no message...)