feat: ✨ decision post on why to use git-cliff for changelogs#273
Open
lwjohnst86 wants to merge 2 commits into
Open
feat: ✨ decision post on why to use git-cliff for changelogs#273lwjohnst86 wants to merge 2 commits into
lwjohnst86 wants to merge 2 commits into
Conversation
signekb
requested changes
Jun 1, 2026
Member
signekb
left a comment
signekb
left a comment
There was a problem hiding this comment.
Very nice 🌷 Some minor suggestions:
| ::::: column | ||
| #### Drawbacks | ||
|
|
||
| - Not nearly as easily customisable as git-cliff (see below). |
Member
There was a problem hiding this comment.
Suggested change
| - Not nearly as easily customisable as git-cliff (see below). | |
| - Not as easily customisable as git-cliff (see below). |
| 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 |
Member
There was a problem hiding this comment.
Suggested change
| information about our context and problem statement as well as the original | |
| information about the context and problem statement as well as the original |
| 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. |
Member
There was a problem hiding this comment.
I think it would make sense to restate/summarise the context and problem statement here.
| 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. |
Member
There was a problem hiding this comment.
Suggested change
| This post explains some of our issues and why we switched to something else. | |
| This post explains some of our issues with Commitizen and why we switched to git-cliff. |
Comment on lines
+37
to
+50
| - 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. |
Member
There was a problem hiding this comment.
Suggested change
| - 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. | |
| - The changelog generated by Commitizen is not as easy to customise, but we need to be able to customise the changelog for different projects, like | |
| the Python packages, R packages, and documentation projects. For example, the website generator | |
| [pkgdown](https://pkgdown.r-lib.org/) for R packages expects a specific format for the | |
| `NEWS.md` file, but we couldn't (easily) modify the changelog template to meet | |
| these requirements. Documentation projects include a lot more changes outside of `refactor`, `fix`, and `feat`, and therefore | |
| some relevant changes to those repos would often be missing from the | |
| changelog. | |
| - 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. |
Seems like item 1 and 3 are very closely related, so attempted to merge then.
| - 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. |
Member
There was a problem hiding this comment.
Suggested change
| - Also written in Rust. | |
| - Is written in Rust. |
| 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 |
Member
There was a problem hiding this comment.
Suggested change
| - It's output is consistent and predictable, which means we can incorporate it | |
| - produces consistent and predictable output, which means we can incorporate it |
| - 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`. |
Member
There was a problem hiding this comment.
Suggested change
| - It can be easily installed and used through `uv` via `uvx`. | |
| - 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 |
Member
There was a problem hiding this comment.
Suggested change
| - It is primarily focused on changelog generation, so we would have to use | |
| - Is primarily focused on changelog generation, so we would have to use |
Member
There was a problem hiding this comment.
primarily? What's other focus areas for them?
| 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. |
Member
There was a problem hiding this comment.
Maybe there's also a consequence to be included here related to the drawback; we need to use another tool for linting and version bumping?
github-project-automation
Bot
moved this from In review
to In progress
in Platform development
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Closes #271
Needs a thorough review.
Checklist
just run-all