Why lint with commitizen

develop
git
standardise
workflow
Reasons to use commitizen to lint our commit messages to follow the Conventional Commits standard.
Published

October 25, 2024

Context and problem statement

Taking time to build automated DevOps processes can save lots of time later on tasks that would normally be manually done. For instance, officially and formally releasing software such as to a software archive like PyPI is a required activity in order for people to be able find and use the software. In order to get on these archives, the software has to be bundled and uploaded. Without DevOps pipelines in place, this activity would need to be done manually, which we want to minimize. So we want to automate the release process. An initial first step is to decide how versions are created, which can be done by following the SemVer practice combined with Conventional Commits. But in order to make sure this is done correctly, commit message structure needs to be verified to follow the Conventional Commits. So the question is:

What tools can we use that verify or reformat commit messages to follow the format needed to help automatically release our software?

Decision drivers

Some motivations are:

  • While as a team we use conventional commits, we can sometimes make mistakes.
  • We can’t guarantee that outside contributors will know about or follow conventional commits.
  • We currently manually fix commits to follow conventional commits in the pull request before merging them in, which can be prone to human error and takes time

Some requirements are:

  • Easy to install
  • Can use on the command line
  • Has GitHub Action workflows available or can be easily made
  • Optionally, has a pre-commit hook available
  • Ideally, does not introduce too many dependencies

Considered options

There are several options available in many programming languages, all called similar or the same name. Given that we work with mostly Python, we’ll only consider Python tools:

commitlint

commitlint is a tool designed to lint your commit messages according to the Conventional Commits standard for your pre-commit hook and GitHub Actions.

Benefits

  • Single purpose is to lint commit messages, which makes it relatively simple to use.

Drawbacks

  • Not actively maintained.
  • Limited documentation.
  • Maintained by a single author.

commitizen

Commitizen is a release management tool designed for teams that follows the conventional commits standard and checks to ensure that standard is followed.

Benefits

  • Maintained by an organization (commitizen-tools).
  • Popular and widely used.
  • Actively and regularly developed.
  • Is part of the official supported pre-commit hooks.
  • Has multiple functionality that includes linting, which means we could use it for other purposes.
  • Extensive documentation.

Drawbacks

  • Has multiple functionality that includes linting, which means we will have to read through the documentation a bit more to learn how to use it.

gitlint

Gitlint checks your commit messages for style.

Benefits

  • Is designed to be used to lint Git messages, so might be a bit easier to use.
  • Fairly popular and widely used.
  • Is part of the official supported pre-commit hooks
  • Well designed documentation

Drawbacks

  • Maintained by a solo author on their personal account, which makes it harder to manage contributors. Plus, author can only work on the project a few times a year.
  • Requires some configuration to follow a specific standard.

Decision outcome

Both gitlint and commitizen are great choices for our requirements. However, the fact that commitizen is under a GitHub organization with several visible contributors means that it is more likely to be stable and sustainable over the longer term than a sole-author project. For that reason, in addition to the fact that commitizen also has other features that we might use in the future, we decided on commitizen to lint our commit messages.

Consequences

  • Based on what I read, it doesn’t seem like it is easy to verify the pull request merge commit message. So we may have to write out our own GitHub Action that will retroactively revert a merged pull request with an incorrect commit message and re-open the pull request.
  • Since commitizen can be used in pre-commit hooks as well as used for other release management purposes, it might save us time later on to use this tool for those purposes.