Use a sigil in commit titles for breaking changes #23

New Issue

GiteaMirror · 2026-02-17T11:33:29-06:00

GiteaMirror commented

2026-02-17 11:33:29 -06:00

Originally created by @DominicKramer on GitHub (Apr 12, 2018).

Currently if a feature, for example, is a breaking change, a commit would look something like the following:

feat: something cool

BREAKING CHANGE: The cool thing broke stuff.

I am suggesting that the standard also allows the use of a special character, for example !, in the title to specify a breaking change. It is a matter of discussion as to whether the body should still contain BREAKING CHANGE.

That is, the above commit could look like the following. Note the ! after feat:

feat!: something cool

BREAKING CHANGE: The cool thing broke stuff.

I am suggesting this change since the GitHub UI and many other tools are used that show only the title of a commit to reduce noise. This is nice, but by looking only at the title, it can be hard to identify which features and chores etc. are breaking changes. The suffix I am proposing would remedy that.

Also, it might be easier to read using a prefix, i.e. !feat: instead of feat!:. This would also be up to discussion.

Originally created by @DominicKramer on GitHub (Apr 12, 2018). Currently if a feature, for example, is a breaking change, a commit would look something like the following: ``` feat: something cool BREAKING CHANGE: The cool thing broke stuff. ``` I am suggesting that the standard also allows the use of a special character, for example `!`, in the title to specify a breaking change. It is a matter of discussion as to whether the body should still contain `BREAKING CHANGE`. That is, the above commit could look like the following. Note the `!` after `feat`: ``` feat!: something cool BREAKING CHANGE: The cool thing broke stuff. ``` I am suggesting this change since the GitHub UI and many other tools are used that show only the title of a commit to reduce noise. This is nice, but by looking only at the title, it can be hard to identify which features and chores etc. are breaking changes. The suffix I am proposing would remedy that. Also, it might be easier to read using a prefix, i.e. `!feat:` instead of `feat!:`. This would also be up to discussion.

GiteaMirror added the suggestion label 2026-02-17 11:33:29 -06:00

GiteaMirror closed this issue

2026-02-17 11:33:30 -06:00

GiteaMirror commented

2026-02-17 11:33:31 -06:00

@damianopetrungaro commented on GitHub (May 2, 2018):

Sometimes it may be useful to catching BC on the fly just reading the first chars of the commit message, see that I do not see a real value around this I would like to ask to @stevemao and @bcoe what do you think about this.

btw @DominicKramer you had a nice idea :)

@damianopetrungaro commented on GitHub (May 2, 2018): Sometimes it may be useful to catching BC on the fly just reading the first chars of the commit message, see that I do not see a real value around this I would like to ask to @stevemao and @bcoe what do you think about this. btw @DominicKramer you had a nice idea :)

GiteaMirror commented

2026-02-17 11:33:32 -06:00

@damianopetrungaro commented on GitHub (Jun 28, 2018):

I'll ping @hbetts too for this.

Sorry for the slow iteration @DominicKramer but I'm having super busy days.

@damianopetrungaro commented on GitHub (Jun 28, 2018): I'll ping @hbetts too for this. Sorry for the slow iteration @DominicKramer but I'm having super busy days.

GiteaMirror commented

2026-02-17 11:33:33 -06:00

@apetro commented on GitHub (Jul 6, 2018):

I agree that it would be helpful for the breakingness of a change to be apparent from the title of the commit message, rather than only signaled in the body or footer. As @DominicKramer notes, there are contexts in which only the title and not the body of a commit message is visible.

For changes that are breaking, the breakingness of the change might be the most important thing to say about the change. So lead with it.

A sigil could work well. It's succinct, it's unambiguous, it could be the first character of the commit message title.

But it also requires learning about Conventional Commits to understand what it means. At a cost of 6 more characters, a prefix before the title like BREAK: ( #64 ) might be understood by someone without special knowledge of Conventional Commits.

The commit message title could also convey the breakingness of the change in zero characters by overloading the type: . Currently type: is typically lowercase; ALL-CAPS could signal that it's a breaking change ( #63 ).

Sigil, an additional BREAK: prefix, ALL_CAPS type, ... something. It would help for the commit title to signal the breakingness of the change.

I am suggesting that the standard also allows the use of

I'd go further. The signal in the commit message title should be REQUIREd rather than just allowed, so that it can be relied upon. Am I not seeing the signal in commit message titles because they're not breaking changes, or because the option to omit the signal was taken? It's a more effective spec feature if it's REQUIREd.

@apetro commented on GitHub (Jul 6, 2018): I agree that it would be helpful for the breakingness of a change to be apparent from the title of the commit message, rather than only signaled in the body or footer. As @DominicKramer notes, there are contexts in which only the title and not the body of a commit message is visible. For changes that are breaking, the breakingness of the change might be the most important thing to say about the change. So lead with it. A sigil could work well. It's succinct, it's unambiguous, it could be the first character of the commit message title. But it also requires learning about Conventional Commits to understand what it means. At a cost of 6 more characters, a prefix before the title like `BREAK: ` ( #64 ) might be understood by someone without special knowledge of Conventional Commits. The commit message title could also convey the breakingness of the change in zero characters by overloading the _type:_ . Currently _type:_ is typically lowercase; ALL-CAPS could signal that it's a breaking change ( #63 ). Sigil, an additional `BREAK: ` prefix, ALL_CAPS type, ... something. It would help for the commit title to signal the breakingness of the change. > I am suggesting that the standard also allows the use of I'd go further. The signal in the commit message title should be REQUIREd rather than just allowed, so that it can be relied upon. Am I not seeing the signal in commit message titles because they're not breaking changes, or because the option to omit the signal was taken? It's a more effective spec feature if it's REQUIREd.

GiteaMirror commented

2026-02-17 11:33:34 -06:00

@apetro commented on GitHub (Jul 9, 2018):

Blogged about desirability signalling API-breakingness of Conventional Commit messages in title rather than just in body or footer.

@apetro commented on GitHub (Jul 9, 2018): [Blogged about desirability signalling API-breakingness of Conventional Commit messages in _title_](https://apereo.github.io/2018/07/07/indicate-breaks-in-conventional-commit-titles/) rather than just in _body_ or _footer_.

GiteaMirror commented

2026-02-17 11:33:35 -06:00

@ChristianMurphy commented on GitHub (Jul 9, 2018):

I like the succinctness of the ! sigil. 👍
It also looks like the meaning should carry over well to non English languages.
English, Spanish, Italian, Polish, and Chinese (the five current translations of conventional commits) all use the exclamation mark in a similar way.

Currently type: is typically lowercase; ALL-CAPS could signal that it's a breaking change

That could also be succinct, but to me sees less intuitive as !.
There would also be significant on the impact on existing tooling, E.G. commitlint type-case would need breaking changes.
It also may not translate as well for readers most comfortable with non-alphabet languages, like Chinese, which don't have letter case.

additional BREAK: prefix, ALL_CAPS type

Again, some concerns on the impact on existing tooling, tools expect type(scope): message.
BREAK: type(scope): message breaks that expectation.
If going down the more verbose route, maybe the existing subtyping system could be leveraged?

category(fix:subcategory): My subject is a valid conventional commit (source)
Maybe break(type:scope): message could allow break to be spelled out without diverging too far from the existing specification?

@ChristianMurphy commented on GitHub (Jul 9, 2018): I like the succinctness of the `!` sigil. :+1: It also looks like the meaning should carry over well to non English languages. English, Spanish, Italian, Polish, and Chinese (the five current translations of conventional commits) all use the exclamation mark in a similar way. > Currently type: is typically lowercase; ALL-CAPS could signal that it's a breaking change That could also be succinct, but to me sees less intuitive as `!`. There would also be significant on the impact on existing tooling, E.G. [commitlint `type-case`](https://github.com/marionebl/commitlint/blob/d636811b4537904231c483a05e91aaf96deb7f6e/%40commitlint/rules/src/type-case.js) would need breaking changes. It also may not translate as well for readers most comfortable with non-alphabet languages, like Chinese, which don't have letter case. > additional `BREAK:` prefix, ALL_CAPS type Again, some concerns on the impact on existing tooling, tools expect `type(scope): message`. `BREAK: type(scope): message` breaks that expectation. If going down the more verbose route, maybe the existing subtyping system could be leveraged? `category(fix:subcategory): My subject` is a valid conventional commit ([source](https://github.com/conventional-changelog/conventional-changelog/blob/0e05028f70bbd3109e1a4b16262a9450153060de/packages/conventional-commits-parser/test/fixtures/log3.txt#L3)) Maybe `break(type:scope): message` could allow break to be spelled out without diverging too far from the existing specification?

GiteaMirror commented

2026-02-17 11:33:36 -06:00

@damianopetrungaro commented on GitHub (Jul 9, 2018):

I think that the ! may be a good one.

About ALL-CAPS i really disagree, it doesn't make anything explicit and may add more cognitive load and this is not good.

Adding the BREAK: as first thing of the commit message, will be really explicit but on the other hand, it will use a lot of chars and tools that may split by : the commit message won't be very happy 😄

@bcoe @stevemao @hbetts this is really a good one IMHO, we may plan to add it in the specs.
If you like the idea too I'm gonna add to the discussion some maintainer of popular tools around conventional-commits.

Let me know!

@damianopetrungaro commented on GitHub (Jul 9, 2018): I think that the `!` may be a good one. About `ALL-CAPS` i really disagree, it doesn't make anything explicit and may add more cognitive load and this is not good. Adding the `BREAK:` as first thing of the commit message, will be really explicit but on the other hand, it will use a lot of chars and tools that may split by `:` the commit message won't be very happy 😄 @bcoe @stevemao @hbetts this is really a good one IMHO, we may plan to add it in the specs. If you like the idea too I'm gonna add to the discussion some maintainer of popular tools around conventional-commits. Let me know!

GiteaMirror commented

2026-02-17 11:33:37 -06:00

@damianopetrungaro commented on GitHub (Jul 16, 2018):

🏓 @bcoe @stevemao @hbetts

@damianopetrungaro commented on GitHub (Jul 16, 2018): 🏓 @bcoe @stevemao @hbetts

GiteaMirror commented

2026-02-17 11:33:38 -06:00

@hutson commented on GitHub (Jul 16, 2018):

I'm ambivalent about this change.

I am suggesting this change since the GitHub UI and many other tools are used that show only the title of a commit to reduce noise.

That seems like something that could, or should, be improved by those tools. Why aren't they recognizing a long-standing convention used by developers to mark breaking changes?

The commit message title could also convey the breakingness of the change in zero characters by overloading the type: . Currently type: is typically lowercase; ALL-CAPS could signal that it's a breaking change ( #63 ).

Not sure how that would work for character based languages (such as Simplified Chinese). (An issue apparently already mentioned by @ChristianMurphy )

I'd go further. The signal in the commit message title should be REQUIREd rather than just allowed, so that it can be relied upon.

I agree with that statement. On a per-project basis, the use of ! must be required. How would that be achieved in practice? How does a team enforce the use of ! for breaking changes?

@damianopetrungaro, yes, please reach out to major language and library ecosystems. Without significant buy-in, I don't think we'll reach the mind share necessary for this change to be recognizable, and therefore, useful.

@hutson commented on GitHub (Jul 16, 2018): I'm ambivalent about this change. > I am suggesting this change since the GitHub UI and many other tools are used that show only the title of a commit to reduce noise. That seems like something that could, or should, be improved by those tools. Why aren't they recognizing a long-standing convention used by developers to mark breaking changes? > The commit message title could also convey the breakingness of the change in zero characters by overloading the type: . Currently type: is typically lowercase; ALL-CAPS could signal that it's a breaking change ( #63 ). Not sure how that would work for character based languages (such as Simplified Chinese). (An issue apparently already mentioned by @ChristianMurphy ) > I'd go further. The signal in the commit message title should be REQUIREd rather than just allowed, so that it can be relied upon. I agree with that statement. On a per-project basis, the use of `!` must be required. How would that be achieved in practice? How does a team enforce the use of `!` for breaking changes? @damianopetrungaro, yes, please reach out to major language and library ecosystems. Without significant buy-in, I don't think we'll reach the mind share necessary for this change to be recognizable, and therefore, useful.

GiteaMirror commented

2026-02-17 11:33:39 -06:00

@hutson commented on GitHub (Jul 16, 2018):

I filed a support request with GitLab to see what they think of the idea of using the existing BREAKING CHANGE: convention - https://gitlab.com/gitlab-org/gitlab-ce/issues/49305

@hutson commented on GitHub (Jul 16, 2018): I filed a support request with GitLab to see what they think of the idea of using the existing `BREAKING CHANGE:` convention - https://gitlab.com/gitlab-org/gitlab-ce/issues/49305

GiteaMirror commented

2026-02-17 11:33:40 -06:00

@bcoe commented on GitHub (Aug 11, 2018):

@hbetts @damianopetrungaro @DominicKramer I'm so so on this idea too. It means that a bunch of tools in the community would need to rework their parsers to parse types with a ! differently.

It would be awesome for tools like GitHub and GitLab to start representing semantic information like BREAKING CHANGE -- I wonder if @zeke has any thoughts on this, who's been advocating using conventional commit messages for electron.

@bcoe commented on GitHub (Aug 11, 2018): @hbetts @damianopetrungaro @DominicKramer I'm so so on this idea too. It means that a bunch of tools in the community would need to rework their parsers to parse types with a `!` differently. It _would_ be awesome for tools like GitHub and GitLab to start representing semantic information like `BREAKING CHANGE` -- I wonder if @zeke has any thoughts on this, who's been advocating using conventional commit messages for [electron](https://electronjs.org/docs/tutorial/electron-versioning#semantic-commits).

GiteaMirror commented

2026-02-17 11:33:42 -06:00

@zeke commented on GitHub (Aug 11, 2018):

@gr2m introduced me to semantic-release about year ago. I was immediately hooked and I've been preaching the semantic gospel ever since. The concept is easy to explain to newcomers until you get to the part about BREAKING CHANGE having to be in the commit "body", which, as many of you have noted, is hidden in many contexts (GitHub, Gitlab, your shell alias for listing one-liner commits)..

I don't read all the Electron issues and PRs in detail (there are too many!), but I skim them all. Having semantic prefixes and the wip app has made skimming much easier. I know what to look at and what I can skip:

I personally like the ! suffix idea.... it might not be completely intuitive without context but it's an easy convention to learn and remember, and it's easy to spot in a list of commits.

The ruby programming language uses ! as a conventional suffix too:

In general, methods that end in ! indicate that the method will modify the object it's called on. Ruby calls these as "dangerous methods" because they change state that someone else might have a reference to.

@zeke commented on GitHub (Aug 11, 2018): @gr2m introduced me to `semantic-release` about year ago. I was immediately hooked and I've been preaching the semantic gospel ever since. The concept is easy to explain to newcomers until you get to the part about BREAKING CHANGE having to be in the commit "body", which, as many of you have noted, is hidden in many contexts (GitHub, Gitlab, your shell alias for listing one-liner commits).. I don't read all the Electron issues and PRs in detail (there are too many!), but I skim them all. Having semantic prefixes and the [wip](http://github.com/apps/wip) app has made skimming much easier. I know what to look at and what I can skip: ![screen shot 2018-08-10 at 3 19 37 pm](https://user-images.githubusercontent.com/2289/43996794-8ae4fd90-9d7f-11e8-9d63-91efd0bd992c.png) I personally like the `!` suffix idea.... it might not be completely intuitive without context but it's an easy convention to learn and remember, and it's easy to spot in a list of commits. The ruby programming language uses `!` as a conventional suffix too: > In general, methods that end in ! indicate that the method will modify the object it's called on. Ruby calls these as "dangerous methods" because they change state that someone else might have a reference to.

GiteaMirror commented

2026-02-17 11:33:43 -06:00

@damianopetrungaro commented on GitHub (Aug 12, 2018):

So I think we can plan to add the ! as breaking change sigil.

Anyone feel free to open a PR if you have time, I am going on vacation, so I'll be free to work on it when I'll be back 😄

@damianopetrungaro commented on GitHub (Aug 12, 2018): So I think we can plan to add the `!` as breaking change sigil. Anyone feel free to open a PR if you have time, I am going on vacation, so I'll be free to work on it when I'll be back 😄

GiteaMirror commented

2026-02-17 11:33:44 -06:00

@nornagon commented on GitHub (Aug 13, 2018):

i'd like to echo the concern that @apetro raised about the ! sigil being unclear to someone who isn't familiar with the conventions, and in addition, it's hard to google.

Perhaps something like breaking-feat: [...] or breaking: feat: [...]?

@nornagon commented on GitHub (Aug 13, 2018): i'd like to echo the concern that @apetro raised about the `!` sigil being unclear to someone who isn't familiar with the conventions, and in addition, it's hard to google. Perhaps something like `breaking-feat: [...]` or `breaking: feat: [...]`?

GiteaMirror commented

2026-02-17 11:33:45 -06:00

@damianopetrungaro commented on GitHub (Aug 13, 2018):

@nornagon messages are cut if they are longer than 50 chars on GitHub UI.

Do you think that it could be worth adding all those chars?

If you have also another single char (or not that much as breaking) in mind feel free to contribute :)

@damianopetrungaro commented on GitHub (Aug 13, 2018): @nornagon messages are cut if they are longer than 50 chars on GitHub UI. Do you think that it could be worth adding all those chars? If you have also another single char (or not that much as `breaking`) in mind feel free to contribute :)

GiteaMirror commented

2026-02-17 11:33:46 -06:00

@bcoe commented on GitHub (Mar 16, 2019):

Since:

we haven't updated the specification to introduce the !.
as @nornagon points out it's potentially confusing.
all of the existing tools support BREAKING CHANGE.
it would be way cooler if we could instead eventually work with gitlab/github folks to consider supporting conventional commits -- catching the BREAKING CHANGE in the message.

I'd like to vote that we don't add this feature to the specification.

@bcoe commented on GitHub (Mar 16, 2019): Since: 1. we haven't updated the specification to introduce the `!`. 2. as @nornagon points out it's potentially confusing. 3. all of the existing tools support `BREAKING CHANGE`. 4. it would be way cooler if we could instead eventually work with `gitlab`/`github` folks to consider supporting conventional commits -- catching the BREAKING CHANGE in the message. I'd like to vote that we don't add this feature to the specification.

GiteaMirror commented

2026-02-17 11:33:47 -06:00

@ofrobots commented on GitHub (Mar 16, 2019):

GitHub and gitlab are but two tools. Having indication of breaking changes
in the abstract that is tool independent would be nice.

On Sat, Mar 16, 2019, 12:50 PM Benjamin E. Coe notifications@github.com
wrote:

Since:

we haven't updated the specification to introduce the !.

as @nornagon https://github.com/nornagon points out it's
potentially confusing.

all of the existing tools support BREAKING CHANGE.

it would be way cooler if we could instead eventually work with
gitlab/github folks to consider supporting conventional commits --
catching the BREAKING CHANGE in the message.

I'd like to vote that we don't add this feature to the specification.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/conventional-commits/conventionalcommits.org/issues/43#issuecomment-473578859,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAE0qSSn_S4Aaniemuy2YsGU3nOp3E05ks5vXUr1gaJpZM4TSKjz
.

@ofrobots commented on GitHub (Mar 16, 2019): GitHub and gitlab are but two tools. Having indication of breaking changes in the abstract that is tool independent would be nice. On Sat, Mar 16, 2019, 12:50 PM Benjamin E. Coe <notifications@github.com> wrote: > Since: > > 1. we haven't updated the specification to introduce the !. > 2. as @nornagon <https://github.com/nornagon> points out it's > potentially confusing. > 3. all of the existing tools support BREAKING CHANGE. > 4. it would be way cooler if we could instead eventually work with > gitlab/github folks to consider supporting conventional commits -- > catching the BREAKING CHANGE in the message. > > I'd like to vote that we don't add this feature to the specification. > > — > You are receiving this because you are subscribed to this thread. > Reply to this email directly, view it on GitHub > <https://github.com/conventional-commits/conventionalcommits.org/issues/43#issuecomment-473578859>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/AAE0qSSn_S4Aaniemuy2YsGU3nOp3E05ks5vXUr1gaJpZM4TSKjz> > . >

GiteaMirror commented

2026-02-17 11:33:48 -06:00

@damianopetrungaro commented on GitHub (Mar 18, 2019):

I think this is the PR with most interaction we ever had!

We can try to add the ! support (or something else too it's fine) because it seems to make sense to a lot of people, and at the same time work with some github/gitlab folks.

Do we know any internal?

@damianopetrungaro commented on GitHub (Mar 18, 2019): I think this is the PR with most interaction we ever had! We can try to add the `!` support (or something else too it's fine) because it seems to make sense to a lot of people, and at the same time work with some github/gitlab folks. Do we know any internal?

GiteaMirror commented

2026-02-17 11:33:49 -06:00

@apetro commented on GitHub (Mar 18, 2019):

For whatever it's worth: after further rumination, I (still) like the ALL-CAPS signifies breaking change idea (#63).

Writing commit messages is like writing email, in that there's a subject and a body and there's lots of contexts in which just the subject will be shown or read. When one wants to SHOUT in email, one writes all-caps. Surely breaking an API is worth SHOUTING about. So when that feature

FEAT: support and require Hipster Ipsum

BREAKING CHANGE: Requires Hipster Ipsum. No longer supports Lorem Ipsum. 
Lorem fails the updated input sanitization filter, which rejects insufficiently hipster 
example text.

was a breaking change, SHOUT IT IN ALL CAPS right at the front of the commit message title, besides offering explicit clarity in the commit message body. 😄

Costs zero characters, all-caps is idiomatic for shouting on the Internet, has the nice side effect of prohibiting shouting when a change is not breaking, and overall less unjustified shouting is a boon.

@apetro commented on GitHub (Mar 18, 2019): For whatever it's worth: after further rumination, I (still) like the ALL-CAPS signifies breaking change idea (#63). Writing commit messages is like writing email, in that there's a subject and a body and there's lots of contexts in which just the subject will be shown or read. When one wants to SHOUT in email, one writes all-caps. Surely breaking an API is worth SHOUTING about. So when that feature ``` FEAT: support and require Hipster Ipsum BREAKING CHANGE: Requires Hipster Ipsum. No longer supports Lorem Ipsum. Lorem fails the updated input sanitization filter, which rejects insufficiently hipster example text. ``` was a breaking change, SHOUT IT IN ALL CAPS right at the front of the commit message title, besides offering explicit clarity in the commit message body. 😄 Costs zero characters, all-caps is idiomatic for shouting on the Internet, has the nice side effect of prohibiting shouting when a change is *not* breaking, and overall less unjustified shouting is a boon.

GiteaMirror commented

2026-02-17 11:33:51 -06:00

@bcoe commented on GitHub (Mar 18, 2019):

@damianopetrungaro, @ofrobots and I have been discussing a compromise; what if we introduced ! as an optional addition to the commit message BUT, it must be used in conjunction with BREAKING CHANGE: description.

How would this land with folks? @hutson, @apetro? @apetro it's worth mentioning that we're adding a stanza to the specification that makes the whole spec case-insensitive, so you could use your approach too.

@bcoe commented on GitHub (Mar 18, 2019): @damianopetrungaro, @ofrobots and I have been discussing a compromise; what if we introduced `!` as an optional addition to the commit message BUT, it must be used in conjunction with `BREAKING CHANGE: description`. How would this land with folks? @hutson, @apetro? @apetro it's worth mentioning that we're adding a stanza to the specification that makes the whole spec case-insensitive, so you could use your approach too.

GiteaMirror commented

2026-02-17 11:33:51 -06:00

@bcoe commented on GitHub (Apr 10, 2019):

@DominicKramer this just landed on master.

@bcoe commented on GitHub (Apr 10, 2019): @DominicKramer this just landed on `master`.

GiteaMirror commented

2026-02-17 11:33:52 -06:00

@bcoe commented on GitHub (Apr 16, 2019):

👋 we are experimenting with the addition of the ! character in the 1.0.0-beta.4 version of the specification.

@bcoe commented on GitHub (Apr 16, 2019): :wave: we are experimenting with the addition of the `!` character in the `1.0.0-beta.4` version of the specification.

GiteaMirror referenced this issue

2026-02-17 11:35:07 -06:00

`docker-compose up` failing #31

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/conventionalcommits.org#23