commitizen-tools
Highlight breaking changes in the changelog
Description
It would be helpful to read a changelog that bumps a major version and to know which one of the changes was a breaking change.
Personally I’m not a fan of icons & emojis so perhaps a section “Breaking changes” would be useful?
I didn’t find an existing discussion on this, surprisingly, but maybe I didn’t spend enough time looking 😉
Possible Solution
No response
Additional context
No response
Related issues
No response
Can you show a commit example? I was under the impression that using BREAKING CHANGE in the body of the commit does that, right?
This commit (including the cz bump):
commit fb71a500ad3ef2678f3c8e6367839b926314fd97 (tag: v10.0.0)
Author: devops <[email protected]>
Date: Fri Jul 25 01:27:02 2025 +0000
bump: release 9.10.1 → 10.0.0
Automatically generated by Commitizen.
commit 13d230527f95605a462de62ef008c0b9c949b9dc
Author: Jens Troeger <[email protected]>
Date: Fri Jul 25 01:44:56 2025 +0200
fix!: enable grpcio types across the entire package (#906)
created the following changelog
## v10.0.0 (2025-07-25)
### Fix
- enable grpcio types across the entire package (#906)
and also the following Github release
Suppose there are multiple commits in that release and only one of them is a breaking change. It’s currently not possible to tell in the changelog and in the release which one of the multiple commits that was.
I was under the impression that using BREAKING CHANGE in the body of the commit does that, right?
I thought/assumed/hoped that the ! in the commit title is sufficient to somehow mark up that particular change as a breaking change. It seems redundant to me to use both ! in the title and BREAKING CHANGE in the body… 🤔
There's not much explanation about this, indeed.
The way I see it (I haven't used ! much personally):
The ! it's only useful to hint a BREAKING CHANGE, but you only want to document what you did: "I fixed foo, this introduced a breaking change". Example commit: fix!: enable grpcio types across the entire package (#906). Of course, commitizen understands this, and identifies a BREAK signal, bumping appropriately.
On the other hand, the "BREAKING CHANGE" in the summary of the commit gives more information.
Example commit:
fix: enable grpcio types across the entire package (#906)
BREAKING CHANGE: by enabling `grpcio`, `foobar` is no longer available, in order to migrate, you have to do X
This would render the following CHANGELOG:
## Fix
- enable grpcio types across the entire package (#906)
## BREAKING CHANGE
- by enabling `grpcio`, `foobar` is no longer available, in order to migrate, you have to do X
Which explains to the end user how to properly take action on an introduced braking change.
However, you could combine both. The ! would work as a hint for developers, for example, on github, you only see the commit title, and then you would know right away. While the BREAKING CHANGE would add documentation for migration purposes on the CHANGELOG.
I'm not sure if there's a proper solution, do you have any suggestions? commitizen is flexible up to a point. But you can always update the changelog after it was generated. Future commitizen executions won't touch your changes.
While I agree with the theory of using BREAKING CHANGE in addition to !, the reality is that many devs are lazy and don’t (seem to) care much about documenting their changes. Requiring such verbose commit messages will in my experience yield no results because devs just won’t bother.
My preference would be for cz to handle commits with a ! in the title and mark up that line item. For example, we could imagine
## Fix
- !enable grpcio types across the entire package (#906)
as a dense solution, or
## Fix
- 🧨 enable grpcio types across the entire package (#906)
or some such. I’m not sure, but I’d like to see support for simple, one-line commit messages because that’s the most I can expect from some devs…
