Repository navigation
Highlight breaking changes in the changelog #1562
Description
Activity
Can you show a commit example? I was under the impression that using
BREAKING CHANGEin the body of the commit does that, right?This commit (including the
czbump):commit fb71a500ad3ef2678f3c8e6367839b926314fd97 (tag: v10.0.0) Author: devops <devops-somecompany@users.noreply.github.com> 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 <jens@some.company> 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 andBREAKING CHANGEin 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 aBREAKsignal, 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 XThis 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 theBREAKING CHANGEwould add documentation for migration purposes on the CHANGELOG.I'm not sure if there's a proper solution, do you have any suggestions?
commitizenis 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 CHANGEin 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
czto 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…
I think we can add options and let the user choose their preference?
I feel we should treat
!asBREAKING CHANGE:🤔## Breaking change * enable grpcio types across the entire package (#906)I thought it should work this way 🤔
Not necessarly @Lee-W because according to semver, you can combine a
fixwith aBREAKING CHANGE. Which translates to "This fixes something but introduces a breaking change by doing so".I think, by default, we could do:
## Fix - [breaking] enable grpcio types across the entire package (#906)
But make the
!configurable, so users could replace[breaking]for an emoji or the!symbol.Just to be clear: according to the conventional commit spec (docs) a commit with a breaking change can be marked in two different ways:
- commit message with a footer
BREAKING CHANGE:, or - append a
!after the type/scope of the message.
This issue here is about marking/emphasizing in a changelog which particular change or commit in a set of changes is a breaking change. This issue isn’t about the commit format itself.
Reacted by Wei Lee- commit message with a footer
Not necessarly @Lee-W because according to semver, you can combine a
fixwith aBREAKING CHANGE. Which translates to "This fixes something but introduces a breaking change by doing so".I think, by default, we could do:
Fix
- [breaking] enable grpcio types across the entire package (build(deps): bump tomlkit from 0.12.1 to 0.12.2 #906)
But make the
!configurable, so users could replace[breaking]for an emoji or the!symbol.Since breaking changes take higher priority, I believe it makes sense to mention them first. By
This fixes something but introduces a breaking change by doing so, it still qualifies as a breaking change.If our changelog is structured like this:
## Breaking Changes ## Features ## Fixes
then I think this change should be included in the first section.
However, if our changelog is organized as follows:
## Features ## Fixes
then your suggestion is certainly better. I would also prefer that breaking changes appear first instead of getting lost in the middle of several commits.
agree with what @jenstroeger suggested, sounds more like the first scenario. or maybe we can provide both ways?
If our changelog is structured like this:
## Breaking Changes ## Features ## Fixes
then I think this change should be included in the first section.
I very much like this suggestion 🙏🏻
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