Why Commitizen for changelog generation
Context and problem statement
When developing software, it is important to keep track of changes made and to communicate these changes clearly to users and contributors. This is especially important in open source projects, such as the Seedcase Project; More people might be contributing to the project and using it in different ways. One way to communicate changes made to a project between releases or versions is by maintaining a changelog. A changelog is a file that contains a chronologically ordered list of changes for each version of a project. It typically includes the version number, release date, and a list of the changes made in that version.
However, creating and maintaining a changelog manually can be time-consuming and error-prone. Fortunately, many tools can automatically generate changelogs based on a project’s history. So the question becomes:
Which tool should we use to auto-generate changelogs for our projects?
Decision drivers
Motivations for this decision include:
- Having a consistent format for changelogs makes it easier for users and contributors to understand and keep track of the changes between versions.
- We do not want to create changelogs manually because it’s time-consuming and error-prone.
- Having a tool that can auto-generate changelogs based on commit messages can help enforce good commit and merging practices.
Requirements for the tool include:
- It should support GitHub Action workflows for auto-generating the changelog
- It should generate changelogs following Semantic Versioning (SemVer).
- It should generate changelogs using commit messages that follow the Conventional Commits specification.
- It should be well-documented and actively maintained.
Considered options
There are numerous tools available for automatically generating changelogs for Git repositories following the Conventional Commit specification, as seen by this list by Conventional Commits. We have considered the following options:
Commitizen
Commitizen is a release management tool designed for teams. By leveraging a standardized commit convention (Conventional Commits by default, but this can be customised), it streamlines the process of version bumping and generating changelogs.
Benefits
- Has GitHub Action workflows to auto-generate the changelog.
- Can generate changelogs based on commit messages following the SemVer and Conventional Commits specification.
- Is well-documented.
- Is actively maintained.
- Will be very easy to implement, since we already use it for linting our commit messages and versioning. I.e., we don’t need to introduce a new dependency and can leverage the existing setup.
- Written in Python, which is a language we are familiar with. This might ease customisation if needed.
Drawbacks
- Not quite as easily customisable as git-cliff, but this might not be required for our use case.
Python Semantic Release
Python Semantic Release is a Python implementation of the Semantic Release tool.
Benefits
- Has GitHub Action workflows to auto-generate the changelog.
- Can generate changelogs based on commit messages following the SemVer and Conventional Commits specification.
- Is actively maintained.
Drawbacks
- Would require additional setup since we are already using Commitizen for linting our commit messages and version bumps.
- A bit difficult to get started with: As detailed in the Semantic release post, their website doesn’t include any tutorials or “getting started” guides.
git-cliff
git-cliff is a changelog generator that can generate changelogs for Git repositories that follow the Conventional Commits specification. It can be customised to generate changelogs in different formats with different filters.
Benefits
- Has GitHub Action workflows to auto-generate the changelog.
- Can generate changelogs based on commit messages following the SemVer and Conventional Commits specification.
- Is well-documented.
- Is actively maintained.
- Can generate changelogs in different formats.
- Allows for filtering commits based on different criteria.
Drawbacks
- Would require additional setup since we are already using Commitizen for linting our commit messages and version bumps.
- For version bumps, it’s not as straightforward as Commitizen to e.g., add the updated version to
pyproject.toml(if we decided to use this for changelog generation we might as well use it for version bumps to keep things simple).
Decision outcome
Both Commitizen and git-cliff are good options for auto-creating changelogs for our projects, since they both meet our requirements. However, we have decided to use Commitizen because we are already using it for linting our commit messages and version bumps. This way we avoid introducing a new dependency and can leverage the existing setup. Implementing this tool will be as easy as setting a configuration variable to true.
Consequences
- To keep the changelog clean and organised, our administrators must follow our merging strategy and ensure that most changes are squashed into a single commit before merging into the
mainbranch. Importantly, the merge commit message should follow the Conventional Commits specification. - In cases where we don’t use squashing, we must ensure that the commit messages follow the Conventional Commits specification.