Use a sigil in commit titles for breaking changes about conventionalcommits.org HOT 21 CLOSED

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.

from conventionalcommits.org.

from conventionalcommits.org.

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.

from conventionalcommits.org.

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?

from conventionalcommits.org.

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.

from conventionalcommits.org.

@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.

from conventionalcommits.org.

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: [...]?

from conventionalcommits.org.

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 :)

from conventionalcommits.org.

I'll ping @hbetts too for this.

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

from conventionalcommits.org.

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

from conventionalcommits.org.

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!

from conventionalcommits.org.

🏓 @bcoe @stevemao @hbetts

from conventionalcommits.org.

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

from conventionalcommits.org.

@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.

from conventionalcommits.org.

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 😄

from conventionalcommits.org.

@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 :)

from conventionalcommits.org.

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?

from conventionalcommits.org.

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.

from conventionalcommits.org.

@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.

from conventionalcommits.org.

@DominicKramer this just landed on master.

from conventionalcommits.org.

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

from conventionalcommits.org.