Conventional commits are a waste of time
Published on Last updated on
The Conventional Commits specification is in its own words a "lightweight convention on top of commit messages" and uses the tagline "A specification for adding human and machine-readable meaning to commit messages". The final version was released in September 2019 and was originally based on the Angular Commit Conventions.
As a reminder or quick introduction, this is the format required by conventional commits:
<type>[optional scope]: <description> [optional body] [optional footer(s)]
First, this article will ignore the optional scope argument, which is totally useless. If you need to know the scope, look at the paths to the changed files, and if that does not indicate the scope, organize your code better.
Looking at the website, it has a subsection titled Why Use Conventional Commits, in which it says (numbers added by me):
- Automatically generating CHANGELOGs.
- Automatically determining a semantic version bump (based on the types of commits landed).
- Communicating the nature of changes to teammates, the public, and other stakeholders.
- Triggering build and publish processes.
- Making it easier for people to contribute to your projects, by allowing them to explore a more structured commit history.
In this article, I will go through every one of these items and explain why I feel like the Conventional Commit specification fails at these goals, in addition to some general remarks about it.
Automatically generating changelogs
Since it is the very first reason they give, one might assume it is one of the primary motivator to adopt this convention. However, this statement completely bypasses the fact that in most cases, changelogs should not be automatically generated.
In an ideal world, a changelog should inform end users about what changed, why they should upgrade, and if applicable, how they should upgrade. An automatically generated changelog from git commits, however conventional they might be, fails at this:
- Either the commits are too big or the changelog will be too detailed. (See later on why that is.)
- The generated changelog will not contain upgrade instructions.
Of course, defenders will now chime in saying like you can add different types to the commit messages, which allows for filtering only certain commits in the changelog. While true, I still believe commits are not the right level of granularity for changelogs. I believe that if you must generate a changelog, you should do so from pull requests (or other change requests systems, like patch sets or merge requests). See below for what I consider a good unit of work for a commit message.
Secondly, an important part of changelogs is indicating an upgrade path for breaking changes. You could put this information inside a git commit description, but a conventional commit lacks the necessary conventions to destinguish these from other descriptions.
Automatically determining a semantic version bump (based on the types of commits landed)
This is technically true. However, you only need part of the specification to achieve this. You could have the convention of requiring a ! in front of a commit message if it is a breaking change.