Why Commitizen for semantic release

communicate
organize
The reasons we use Commitizen for automated versioning and releasing of our software.
Published

November 8, 2024

Context and problem statement

Setting and updating the version of software communicates to users the state and changes of software. However, having to manually update the version as well as deciding when a given state of the software requires a version is time- and energy-consuming. So instead, we would rather automate this process. So the question is:

What tool can we use that will automate versioning for us?

Decision drivers

The main drivers for this decision are that:

  • We don’t want to manually have to update the version number in files throughout our software.
  • We don’t want to manually add Git tags for the versions.
  • We want the version to be determined based on some principles, rather that just a “feeling” or potentially arbitrary decision.

Our requirements for the tool are that it:

  • Follows Semantic Versioning.
  • Relies on Conventional Commits to determine which version to set.
  • Includes GitHub Action workflows to auto-generate releases upon merging to the main branch.
  • Updates the version number in the pyproject.toml file.
  • Creates a Git tag for the release.

Considered options

There are only two options that fit our requirements:

While most package management systems like Poetry, which we already use, can do version updating and releasing, they don’t rely on automation based on commit messages. For this reason, we don’t consider them.

Python Semantic Release

Automatically updates version information for Python projects.

Benefits

  • Widely used with a large number of GitHub stars.
  • Often recommended on external guides and websites (e.g. the Python Packages book).
  • Very actively maintained and developed.
  • Can also generate an auto-generated changelog.

Drawbacks

  • The website is difficult to navigate, relative to Commitizen at least. For instance, there aren’t any tutorials or “getting started” guides and the colour scheme is a bit hard on the eyes.

Commitizen

Commitizen is a Python CLI tool to help manage releases, versioning, and creating and adhering to Conventional Commits.

Benefits

  • We already use it for our commit linting.
  • The documentation and website are very easy to navigate and understand.
  • Very widely used with a large number of GitHub stars.
  • Very actively maintained and developed.
  • Can also generate an auto-generated changelog.

Drawbacks

  • None.

Decision outcome

The choice was pretty clear that Commitizen was the best for our requirements and purposes. We already use it and the documentation is much easier to navigate and use, which is a critical factor in choosing between tools.

Consequences

  • Because it’s a tool we already use, integrating it should be fairly easy.

Resources used for this post