From 35c81fdfeec8f4b43007858d86695c1712766afb Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Fri, 22 May 2026 17:59:46 +0200 Subject: [PATCH] =?UTF-8?q?feat:=20=E2=9C=A8=20decision=20post=20on=20why?= =?UTF-8?q?=20to=20use=20git-cliff=20for=20changelogs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- why-changelog-with-commitizen/index.qmd | 232 ++++++++++++------------ why-changelog-with-git-cliff/index.qmd | 156 ++++++++++++++++ 2 files changed, 269 insertions(+), 119 deletions(-) create mode 100644 why-changelog-with-git-cliff/index.qmd diff --git a/why-changelog-with-commitizen/index.qmd b/why-changelog-with-commitizen/index.qmd index 4bfa67a..e1b3f0c 100644 --- a/why-changelog-with-commitizen/index.qmd +++ b/why-changelog-with-commitizen/index.qmd @@ -2,11 +2,19 @@ title: "Why Commitizen for changelog generation" description: "Our reasons for using Commitizen to auto-generate changelogs." date: "2024-11-22" +date-modified: "2026-05-22" +previous: true categories: -- develop -- git + - develop + - git --- +::: callout-warning +We no longer use Commitizen for changelog generation. See our [post on using +git-cliff for changelog generation](/why-git-cliff/index.qmd) for more +information about our new setup. +::: + ::: content-hidden Use other decision posts as inspiration to writing these. Leave the content-hidden sections in the text for future reference. @@ -15,187 +23,172 @@ content-hidden sections in the text for future reference. ## Context and problem statement ::: content-hidden -State the context and some background on the issue, then write a -statement in the form of a question for the problem. +State the context and some background on the issue, then write a statement in +the form of a question for the problem. ::: -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: +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 ::: content-hidden -List some reasons for why we need to make this decision and what things -have arisen that impact work. +List some reasons for why we need to make this decision and what things have +arisen that impact work. ::: 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. +- 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](/why-semver/index.qmd) (SemVer). +- It should support GitHub Action workflows for auto-generating the changelog +- It should generate changelogs following [Semantic + Versioning](/why-semver/index.qmd) (SemVer). - It should generate changelogs using commit messages that follow the - [Conventional Commits](/why-conventional-commits/index.qmd) - specification. + [Conventional Commits](/why-conventional-commits/index.qmd) specification. - It should be well-documented and actively maintained. ## Considered options ::: content-hidden -List and describe some of the options, as well as some of the benefits -and drawbacks for each option. +List and describe some of the options, as well as some of the benefits and +drawbacks for each option. ::: -There are numerous tools available for automatically generating -changelogs for Git repositories following the Conventional Commit -specification, as seen by -[this list](https://www.conventionalcommits.org/en/about/#tooling-for-conventional-commits) +There are numerous tools available for automatically generating changelogs for +Git repositories following the Conventional Commit specification, as seen by +[this +list](https://www.conventionalcommits.org/en/about/#tooling-for-conventional-commits) by Conventional Commits. We have considered the following options: - [Commitizen](https://commitizen-tools.github.io/commitizen/) -- [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) +- [Python Semantic + Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) - [git-cliff](https://git-cliff.org/docs/) ### Commitizen -[Commitizen](https://commitizen-tools.github.io/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. +[Commitizen](https://commitizen-tools.github.io/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. -::::: columns -::: column +::: columns +::::: column #### Benefits - Has GitHub Action workflows to auto-generate the changelog. -- Can generate changelogs based on commit messages following the SemVer - and Conventional Commits specification. +- 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](/why-lint-with-commitizen/index.qmd) and - [versioning](/why-semantic-release-with-commitizen/index.qmd). 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. - -::: +- Will be very easy to implement, since we already use it for [linting our + commit messages](/why-lint-with-commitizen/index.qmd) and + [versioning](/why-semantic-release-with-commitizen/index.qmd). 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. +::::: -::: column +::::: column #### Drawbacks -- Not quite as easily customisable as git-cliff, but this might not be - required for our use case. - -::: +- Not quite as easily customisable as git-cliff, but this might not be required + for our use case. ::::: +::: ### Python Semantic Release -[Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) -is a Python implementation of the -[Semantic Release](https://semantic-release.gitbook.io/semantic-release/) -tool. +[Python Semantic +Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) is +a Python implementation of the [Semantic +Release](https://semantic-release.gitbook.io/semantic-release/) tool. -::::: columns -::: column +::: columns +::::: column #### Benefits - Has GitHub Action workflows to auto-generate the changelog. -- Can generate changelogs based on commit messages following the SemVer - and Conventional Commits specification. +- Can generate changelogs based on commit messages following the SemVer and + Conventional Commits specification. - Is actively maintained. +::::: -::: - -::: column +::::: column #### 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](/why-semantic-release-with-commitizen/index.qmd#python-semantic-release), - their website doesn't include any tutorials or "getting started" - guides. - -::: +- 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](/why-semantic-release-with-commitizen/index.qmd#python-semantic-release), + their website doesn't include any tutorials or "getting started" guides. ::::: +::: ### git-cliff -[git-cliff](https://git-cliff.org/docs/) 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. +[git-cliff](https://git-cliff.org/docs/) 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. -::::: columns -::: column +::: columns +::::: column #### Benefits - Has GitHub Action workflows to auto-generate the changelog. -- Can generate changelogs based on commit messages following the SemVer - and Conventional Commits specification. +- 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. +::::: -::: - -::: column +::::: column #### 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). - -::: +- 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 ::: content-hidden -What decision was made, use the form "We decided on CHOICE because of -REASONS." +What decision was made, use the form "We decided on CHOICE because of REASONS." ::: -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`. +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 @@ -203,14 +196,14 @@ variable to `true`. List some potential consequences of this decision. ::: -- To keep the changelog clean and organised, our administrators must - follow our - [merging strategy](https://team.seedcase-project.org/how-we-work/admin#merging-topic-branches) - and ensure that most changes are squashed into a single commit before - merging into the `main` branch. 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. +- To keep the changelog clean and organised, our administrators must follow our + [merging + strategy](https://team.seedcase-project.org/how-we-work/admin#merging-topic-branches) + and ensure that most changes are squashed into a single commit before merging + into the `main` branch. 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. ## Resources used for this post @@ -219,6 +212,7 @@ List the resources used to write this post ::: - [Commitizen](https://commitizen-tools.github.io/commitizen/) -- [Python Semantic Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) +- [Python Semantic + Release](https://python-semantic-release.readthedocs.io/en/latest/index.html) - [git-cliff](https://git-cliff.org/docs/) - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) diff --git a/why-changelog-with-git-cliff/index.qmd b/why-changelog-with-git-cliff/index.qmd new file mode 100644 index 0000000..70c7915 --- /dev/null +++ b/why-changelog-with-git-cliff/index.qmd @@ -0,0 +1,156 @@ +--- +title: "Why git-cliff for changelog generation" +description: "Automatically generating a changelog can save a lot of administrative time, especially for a small group like ours. This post explains our reasons for using git-cliff to auto-generate changelogs." +date: "2026-05-22" +categories: + - develop + - git +--- + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a statement in +the form of a question for the problem. +::: + +We originally used Commitizen for changelog generation, but we encountered some +issues and limitations to it as our needs grew. So this post is explaining why +we switched to git-cliff. See our [previous post on using Commitizen for +changelog generation](/why-changelog-with-commitizen/index.qmd) for more +information about our context and problem statement as well as the original +reasons for using Commitizen. + +This post explains some of our issues and why we switched to something else. + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things have +arisen that impact work. +::: + +Commitizen worked fairly well for our needs for a while, but as we incorporated +it in other, non-Python projects, we quickly started encountering some issues +and limitations. Some of the issues we encountered include: + +- The changelog generated by Commitizen is not as easy to customise. For + example, in R packages, the website generator + [pkgdown](https://pkgdown.r-lib.org/) expects a specific format for the + `NEWS.md` file, but we couldn't (easily) modify the changelog template to meet + these requirements. +- When generating the changelog to be included in the GitHub release notes, it + would often add a commit message at the end of the changelog. It wasn't clear + how to remove it or even where it came from, as the CLI didn't produce the + same output. +- We wanted to be able to customise the changelog for different projects, like + the previously mentioned R packages, but also for documentation projects, + which include a lot more changes outside of `refactor`, `fix`, and `feat`. So + some relevant changes to those repos would often be missing from the + changelog. +- We wanted something built in a more "formal" programming language, especially + with the increase in supply chain attacks on e.g. Node.js packages. This isn't + critical, but it does need to support diverse project types, not just e.g. + Python projects. + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits and +drawbacks for each option. +::: + +There are numerous tools available for automatically generating changelogs for +Git repositories following the Conventional Commit specification, as seen by +[this +list](https://www.conventionalcommits.org/en/about/#tooling-for-conventional-commits) +by Conventional Commits. We have considered the following options: + +- [Cocogitto](https://cocogitto.github.io/) +- [git-cliff](https://git-cliff.org/docs/) + +These were the only two that fit our needs and importantly were still actively +maintained. Most of the other options hadn't been updated in years. + +### Cocogitto + +[Cocogitto](https://cocogitto.github.io/) is primarily focused on bumping +versions and helping to release them, checking commits match Conventional +Commits style, and for creating Conventional Commits. However, it does have a +changelog generation feature. + +::: columns +::::: column +#### Benefits + +- Is very well developed and documented. +- Can create custom changelogs using the [tera](https://keats.github.io/tera/) + templating engine. +- Written in Rust, which is a powerful, statically-typed language that is known + for its performance and safety. +::::: + +::::: column +#### Drawbacks + +- Not nearly as easily customisable as git-cliff (see below). +::::: +::: + +### git-cliff + +[git-cliff](https://git-cliff.org/docs/) 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. + +::: columns +::::: column +#### Benefits + +- Can generate changelogs based on commit messages following the SemVer and + Conventional Commits specification. +- Is very well-documented. +- Is actively maintained. +- Can generate changelogs in different formats. +- Allows for filtering and pre-processing of commits based on different criteria + and patterns, which is really useful for us since we have different types of + projects that require different processing needs. +- Also written in Rust. +- It's output is consistent and predictable, which means we can incorporate it + easily into our workflow for generating GitHub release notes. +- It can be easily installed and used through `uv` via `uvx`. +::::: + +::::: column +#### Drawbacks + +- It is primarily focused on changelog generation, so we would have to use + another tool for linting and version bumping. +::::: +::: + +## Decision outcome + +We have decided to use git-cliff because it is highly customisable, which means +we can make it fit our needs for all our different projects. + +### Consequences + +- Because of our need to make custom changelogs for different projects, the + maintenance cost will be higher than if we used something with defaults that + were closer to what we needed. But unfortunately, there isn't a tool that can + meet all our needs without some customisation, so we have to accept this + trade-off. +- We introduce a new dependency, which brings with it some costs to security and + maintenance. But git-cliff is actively maintained and written in Rust (which + is known for its safety), so we accept this trade-off as well. + +## Resources used for this post + +::: content-hidden +List the resources used to write this post +::: + +- [Conventional Commits + tooling](https://www.conventionalcommits.org/en/about/#tooling-for-conventional-commits)