I am co-maintaining a few crates in the Rust ecosystem. Some very passively, some (config-rs) more actively. From time to time, and lately more frequently, I see more and more “conventional commits”. I hate them with a passion and for the repositories I frequently ask people to rewrite their commit message. I even went as far as picking their commits to my local repository and rewriting the commit messages by hand (yes, FOR THEM even though it is not my job).

What “Conventional Commits” are

Conventional commits is a (pseudo)standard. Its tagline is

A specification for adding human and machine readable meaning to commit messages

and it advertises itself as a “lightweight convention on top of commit messages” (source).

The idea behind conventional commits is that one can write tools to parse commit messages and process the found data, for example to generate changelogs. Other uses come to mind, for example for gathering statistics (“who writes the most 'feature' commits?”).

The Premise is wrong!

The premise that generating a changelog from git commits is a good idea is utterly wrong, though.

First of all, commit messages are there for developers of a software to understand why you did what to achive what goal (see also: 1, 2, 3). Generating changelogs from commits results in not very much more than git shortlog lastrelease..currentrelease. Changelogs are mainly for the users of the software. These users might be developers, if the project is a library, but the point stands. A user of a software should never have to concern themselves with stuff that happened during the development of the next release of that software. They are concerned about what changed for them. These things might overlap, yes, but they are never equal!

Conventional Commits hurt!

From the real world out there – from maintaining a few software projects – I can tell you this: Not ONE SINGLE conventional commit message I've seen in recent years did actually a good job. None, yes I say it again: NONE, has actually described what the commit was about!

That's of course not necessarily a fault of the idea of having machine-readable commits, but a direct result. Why? Because people start thinking that now that they're writing a “machine readable” format in their commit message, they provide more value in the commit message than before. This results in shorter commit messages with fewer details.

Fun is, that the website for conventional commits actually markets this:

feat: allow provided config object to extend other configs

BREAKING CHANGE: extends key in config file is now used for extending other config files

That's the first example on the website. What does this commit message actually tell us? It tells us that in the software project at hand, there is a “config object” and that now this object can be used to extend other configs.

Fine.

It does not tell us why this change was made (other than that it is a new feature now) and it does not tell us what was done for this to become possible. It tells us that there is a breaking change, but it does not tell us why there was this breaking change, whom this may concern, why this might be a problem even, or how users should react to this breaking change.

Further, I deduct that this change might be a complex one. Of course, nobody can tell from the commit message alone, but lets just assume for one minute that introducing this change actually entailed a few hundret lines of code added to the codebase of the project and another few tens of lines changed.

I can almost guarantee you (haha, you may think... guarantee with a fictional software project – yes! Please stay with me here), that implementing this change in not one commit but maybe three or more seperate commits, one atomic change after another, would result in a way better history! Way better discoverability for developers!

After the change was accepted, the cover-letter, pull/merge request description or merge commit itself can of course contain a detailed description that later might end up in a CHANGELOG.md file (although some argue that having such a file is not beneficial in any way).

How to do better

It is so easy to do better than conventional commits! Actually, there are only seven rules you must follow for nice commit messages! Just read this article – or, if you're lazy, I copy them for you here:

1. Separate subject from body with a blank line
2. Limit the subject line to 50 characters
3. Capitalize the subject line
4. Do not end the subject line with a period
5. Use the imperative mood in the subject line
6. Wrap the body at 72 characters
7. Use the body to explain what and why vs. how

It's as simple as that.

I would even add another rule: Use --signoff when committing for using the Developer Certificate of Origin (see also 1, 2).

Recently, I voiced my discomfort... no, lets face it: my anger with people that cannot obey the simplest commit message rules:

Why can't people obey these simple #commit message rules?

• Use an uppercase letter for the start of your subject line
• EXPLAIN what you did, not “Fixes”

#git

(toot)

This really bothers me. I (co-)maintain a few crates in the #rust ecosystem. There are contributions rolling in every other week and I love that, because it makes me happy to see that other people care about the same things that I care about. Still, I am constantly asking people to rewrite commit messages or clean up their branches because they did strange things – for example merge the master branch instead of rebasing their pull-request to fix merge conflicts. And sometimes even change things in this merge commit, making a review utterly impossible!

Most of the time I do not bother if people just don't capitalize the first letter of their commit message, but it bothers me to no end, still. That's why I teach others to write proper commit messages when I teach them how to use #git, and I really try to be a pain in their ... youknowwhat, so they are annoyed by me telling them “No, rephrase that!” all the time!

I am not angry if people fail to use git trailers the right way (and yes, these are kernel commit conventions. Does not mean they cannot be applied to other workflows as well)! These rules are, of course, not carved into stone. Still, it is a matter of good behaviour in the community to give attribution to people involved in the process of applying the patch (using “Signed-off-by”, “Acked-by” or “Reviewed-by”), crafting the patch (using “Co-authored-by”, “Suggested-by”, “Signed-off-by”) or others (“CC”, “Reported-by”, ...).

I hope I don't have to repeat that commit messages like “Fixes” or “Refactor” are bullshit!

How to NOT do better

There are projects out there that try to make you a better committer. Most known is conventional commits.

I don't like these things at all. “Why?” you may ask? The answer to that is really simple: It makes you think less about what you've done, and, and that's propably the worst thing, it gives you the ability to auto-generate a changelog from your commit logs. But commit logs are not changelogs. Commit logs are logs of steps how your software was developed. A changelog is a list of things your users need to know about when upgrading from one version to another. They don't need to know the steps that where taken to provide new features, fix bugs or refactor your codebase, they need to know about what changes for them, how using the product has changed!

Luckily I have managed to stay away from projects using conventional commits.

How to do better

There are tons and tons of guides out there how to write proper git commit messages. I leave searching for them as a task for the reader here (one thing I want to link here is Drew DeVault's article on a disciplined git workflow). The very basics are:

• The subject line must not exceed 50 characters
• The subject line should be capitalized and must not end in a period (really, who on earth would end it with a period? I mean... do you end your email subjects with a period?)
• The subject line must be written in imperative mood (“Fix”, not “Fixed” / “Fixes” etc.)
• The body copy must be wrapped at 72 columns
• The body copy must only contain explanations as to what and why, never how. The latter belongs in documentation and implementation.
  

There are, of course tons of great examples out there. And because people get annoyed if I tell them that the best examples can be found in the linux kernel community (“These people are GODs, I cannot compare to them” – why not?), I can only show you some less GODish commits (by me)!

Have a look at my

• contribution to shiplift. The commit message is not that long and the change is atomic. The subject line is a short summary what the change is about, the body explains why this is/was done. The trailer notes that I submitted this according to the developercertificate.
• contribution to config-rs. Nobody said that the commit subject has to explain all the things – as long as there is reasonable explanation in the body, the subject can be “Simplify implementation” (like here).
• commit bringing order to the galaxy. There can be the occasional joke, of course!

These are all rather short commit messages for simple patches. Longer messages with more explanations also exist in my projects! For example in the butido project there are changes like this one, or this one or even this very long one. Or, to go crazy, this enormous one here.

These commits have one thing in common: They explain why things were done.

And you can do that to! One really simple idea that is worth trying out is not to use the -m flag of git-commit at all. This way you are presented with your favourite editor and can pause for a moment to think about what to write.

Don't be that guy that appears on the front page of commitlogsfromlastnight.com!