I hate Conventional Commits

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).