Denote API breaking changes

[olivierlacan]

We have a Changed section but some changes may be breaking and others not. This information can be encoded in the release version if the maintainer follows Semantic Versioning but unless this adherence is explicitly stated in the change log (I think it should, which we should address) we can't assume that readers of the change log know that a major version bump often comes with the introduction of API breaking changes.

So far I've seen and used this syntax:

## 1.0.0 - 2014-12-13
### Changed
- [breaking] removed method x

While it does the job of calling attention to the breaking change, it's inconsistent with the idea I submitted for yanked releases in #35. I think a breaking change should warrant as much if not more attention than a yanked release. So perhaps:

## 1.0.0 - 2014-12-13
### Changed
- [BREAKING] removed method x

Sure it's ugly, but it does the job. With several independent breaking changes though it gets real ugly:

A way to fix that would be to use Markdown's emphasis:

## 1.0.0 - 2014-12-13
### Changed
- **BREAKING**: removed method x

This one looks a bit more civilized:

It might be worth extending this syntax to yanked as well since square brackets have no emphasis meaning in Markdown and conflict with link tags a bit.

[barraponto]

Agreed. And of course they should all be grouped together under Changed/Removed.

[leoj3n]

https://github.com/caskroom/homebrew-cask/blob/master/doc/CHANGELOG.md

[lunemec]

I personally would use other word than 'breaking', it sounds too much like 'breaking news!' :)

[danzilio]

It might be worth adding a breaks section to the spec. We currently have added, changed, deprecated, removed, fixed, and security specifically because they call out important information. Of course, we can have items in the changed section that aren't necessarily breaking changes. I think breaking changes are important enough to call out in their own section. I know this information is encoded in SemVer, but I think this breaks section could go a long way when trying to communicate what the breaking changes were that warranted a bump in the major version.

[kossnocorp]

👍 for **BREAKING**, less is more.

[ScottFreeCode]

That particular example strikes me as Removed rather than Changed. I'd also be concerned that with breaking and non-breaking Changed entries, we'd just shift the ambiguity to a different question: should I put backwards-compatible enhancements in Added because they're purely additions to the interface, or in Changed without breaking tags because they're somehow not big enough to be Added or aren't full features in their own right -- and that ends up dragging in the question, what's a full feature in its own right. Best-case scenario, I still have to remember what my philosophical choices are in that regard and there's arguably more opportunity for inconsistency or opportunity for more dangerous inconsistency (because if I ever forget the Changed+[breaking] convention and use Added for non-breaking and just Changed for breaking, then some of my just Changed entries are non-breaking in contrast to Changed+[breaking] and others are breaking in contrast to Added). Plus, it makes the otherwise implicit relationship of change-log change types to interface evolution (what semantic versioning addresses) explicit, but only explicit in one case instead of consistently for all -- and the alternative, adding breaking and/or non-breaking for all relevant groups, would be mostly redundant with both the rest of the grouping info in the change log and with semantic versioning, which suggests that maybe this info shouldn't have to be embedded in an additional manner in the first place.

As it stands, I can pick one of two philosophies: either the change log doesn't need to correspond perfectly to backwards-compatibility/incompatibility interface documentation, and the difference between "breaking" and "non-breaking" Changed entries doesn't matter, or it does, and any backwards-compatible change is technically Added -- however small -- rather than Changed. Once I decide whether I care about having the same kind of strict backwards-compatibility info in the change log as in semantic versioning, all I have to do is apply it consistently; the hard part is deciding in the first place and remembering the decision as the change log evolves. So, individual entries shouldn't need to be tagged for this, just document at the top (next to but distinct from whether the project's versioning scheme is semantic) whether "Added" and "Changed/Removed" in the change log correspond to backwards-compatible and backwards-incompatible changes respectively or merely to whatever the change naturally seems like from a less compatibility-centric level.

Tangentially, I also don't like the term "breaking" to begin with: it can mean backwards-incompatible interface changes (this is what semantic versioning is concerned with, and so far change-logs are not directly concerned with), but it can also mean just plain old breakage-in-practice, which happens in bugs here and there regardless of the interface versioning or (more to the point here) the type or intention of the changes. I've seen people argue that semantic versioning doesn't work because any change can break code; the problem with such criticism is that's not the type of "breaking" that semantic versioning is directly concerned with (although what it is concerned with, the definition of interfaces, contributes greatly to managing actual breakage), but to clear up the confusion we have to use less ambiguous language. The semantic versioning spec itself avoids this ambiguity by focusing on interfaces and backwards-compatibility or incompatibility; it's a pity more semantic versioning practitioners don't follow its linguistic lead. Anyway, that particular terminology is not necessarily the right solution for a change log (what a change log talks about may not be as clear-cut as a programming interface), but it's a good example of the problem with the particular terminology of "breaking changes", and the semantic versioning spec is a good example of how focusing on what you really want to talk about in the first place can really clear up what you say about it.

[Ajedi32]

Maybe this is a bit naive, but shouldn't the section each change is in denote whether or not it's breaking?

• Changes under Fixed and Security are non-breaking, SemVer-Patch changes
• Changes under Deprecated and Added are non-breaking, SemVer-Minor changes
• Changes under Removed and Changed are breaking, SemVer-Major changes

[Fryguy]

We have a Changed section but some changes may be breaking and others not. This information can be encoded in the release version if the maintainer follows Semantic Versioning but unless this adherence is explicitly stated in the change log (I think it should, which we should address) we can't assume that readers of the change log know that a major version bump often comes with the introduction of API breaking changes.

Even if you follow semver and have a version bump, it can include a lot of non-breaking changes as well, so I really love having a way to formally denote which of the changes (or fixes or whatever) are breaking and which aren't. This can aid readers in knowing what they have to do to their calling code in order to upgrade to the latest version.

[majormoses]

Moving this from my previous issue #200

I am a maintainer for 180+ sensu plugins and extensions and we use this as a great base, we found that users really liked calling out breaking changes more obviously as it allowed them very quickly evaluate and determine an upgrade path.

Most of the time the most important questions to be asked are:

• is there a breaking change? Does it affect me?
• is there a new feature/fix I could use that requires no effort other than pulling in the new version?

Anyways just wondering if it makes sense to attempt to get something like this into wider practice or if we should just create our flavor on top like we started doing. Here is an example of how we started doing it: https://github.com/sensu-plugins/sensu-plugins-aws/blob/8.0.0/CHANGELOG.md and our community has responded very positively to this.

[majormoses]

Here is something I published for our community describing "The Breaking Change": https://github.com/sensu-plugins/community/blob/master/HOW_WE_CHANGELOG.md#the-breaking-change

One point that I have yet to see someone bring up is that even an added feature can be a breaking change if it requires a new dependency. This is why We decided to always make it very clear to a user when they need to pay attention.

[majormoses]

Maybe this is a bit naive, but shouldn't the section each change is in denote whether or not it's breaking?

As I just pointed out adding a new feature with a new external dependency still makes it a breaking change. If the goal of a CHANGELOG is to indeed track the changes and help evaluate upgrade path I think it makes sense to call these out appropriately.

[gilmrjc]

I'm in favor of using a BREAKING: tag instead of a new section. It's visually stronger, at least in my opinion.

[majormoses]

I'm in favor of using a BREAKING: tag instead of a new section. It's visually stronger, at least in my opinion.

How is a large header (in bold) less obvious than some bold text?

Breaking Change

• added dependency of package foo that requires client libs for foo to be installed on the system. You will need a c compiler to install them.

vs

Changed

• BREAKING added dependency of package foo that requires client libs for foo to be installed on the system. You will need a c compiler to install them.

maybe it's just me but having it as it's own header is way more obvious to me and the hundreds of people in our community that were very happy with this switch.

[gilmrjc]

The header is more obvious because the list you use as an example have just one item, but if the list is longer it's more obvious where are the breaking changes

Changed

• BREAKING: Here goes a message a breaking change introduced in this version
• BREAKING: Another message a breaking change introduced in this version
• BREAKING: Did I told you I break?
• BREAKING: Look in the docs for more instructions if you want to upgrade to this version
• Non breaking changes introduced in this version
• Similar change in this version
• Refactored methods
• Changed syntax format used

I can distinguish the breaking changes even if I don't see the header. If the change log grows long enough to make me scroll, it's easier to spot using a tag than a header.

Anyway, this is a set of guidelines to encourage people to keep a change log. If using headers works for you, it's ok. I've seen projects where every change creates a new version. I guess a new section is better there, but for projects where there are more than a couple of changes every version, I feel the tag is more readable. The only thing I know for sure it that we need more opinions on this.

[Fryguy]

I've used the **BREAKING**: format in a number of gems already and it has worked out really well. It's very clear why you bumped a major version, particularly if you put them at the top of the list of changes as @gilmrjc did in his example.

[dominiksalvet]

I personally indicate breaking changes only by increasing the major version of my projects as stated in the SemVer. However, the idea to distinguish between compatible and incompatible changes somehow incorporated right into changelog items is justified as programmers using your projects can quickly identify those breaking changes and so they don't have to read through the whole changelog of a new release, which can be really long sometimes.

Next point I would like to state is that changelog should be updated during the development, not right before releasing a new version. Therefore, programmers depending on your project can react to those breaking changes even before you publish a release. Otherwise, they would have been noticed after release and only by increasing the major version.

The last thing I would like to share my opinion on is **BREAKING**-like per-item indicator vs ### Breaking changes section. Well, changelog based on Keep a Changelog proposes some types of changes, e.g., Added, Changed, Deprecated, etc. When considering the title for all breaking changes, it is good to note that not all breaking changes are actually Changes as per Keep a Changelog types of changes. What I mean is that a breaking change may be of Removed type or Added type, in which case the single title Breaking changes is not accurate enough. The opposite way, to have a new title for each type of breaking change, e.g., Breaking removed, Breaking added, Breaking changed, etc., introduces so many types that final changelogs would not be so clear anymore. So here I am for a **BREAKING**-like per-item solution in any type, not just Changed.

It has been a while since this issue was being discussed, so I would really love to hear about its current state and impacts if any.

[majormoses]

@dominiksalvet I 100% agree with your first two points and I make them regularly.

On the note of Breaking and Breaking Changes as a header, I agree if you don't have descriptive entry than it fails to convey the type of change. I also see your point about divergence from denoting the type of change in the header. I would argue that Breaking (or Incompatible if you prefer) is almost its own type but at this point I don't want to beat the dead horse. It does buck the current mold but that does not mean that the mold is perfect or that its bad. It just means there is a change of some kind which requires a consumer to evaluate. Not all breaking changes break all users in fact many breaking changes only affect a very small subset of the use cases and therefore users want to quickly discover where to spend their efforts. I would not be opposed to using Breaking as a header if that makes the difference even though I think it feels odd as it does not convey a behavior change. In all cases where something is breaking the behavior changes even if you are adding a feature/interface if it is required or you are changing the default for a previous default. As such I find Breaking Changes quite appropriate if you write good changelogs which is what all of this is about right? If we do a per item tag/bold that may mean reading multiple sections which I think defeats much of the purpose to very quickly identify the integration considerations to use the new version.

I think the most important thing is to figure out who your demographics are for consuming your changelog. While it's great to follow some "golden community standard" not all communities share the same demographics, what makes sense for one does not make sense for another. In my case I polled (several times) with my community and they have been instrumental in forming my opinion rather than asking a group that may not be your target demographic. Let's face it we have to be a special kind of geek to spend years discussing how to communicate changes but can't agree on something as simple as bold, header, tags, or that we even need a change in the first place 😉.

While I would love to see something be officially adopted here it does not sound like there is any consensus as to how to proceed and I am more than happy to continue to follow my own flavor in the meantime.

[dominiksalvet]

@majormoses You made a good point about the individual section for breaking changes as for quickly identify breaking changes, which in case of per-item could be a little tricky - namely for longer version changelogs. Also, I must admit that if we would use per-item indicator, it could steal users attention (not only the programmers depending on a project) from, e.g., new features or changes made in a compatible way that are not highlighted/prefix with something like BREAKING, which could be shame.

Well, I guess you have convinced me with your arguments. Also, you are right that breaking changes are so important for some developer that they should be in its own section. I was stuck in the Changed -> Breaking changes, Remove -> ???, New -> ???, etc. analogy.

Your flavor looks great but I would rather stay with Keep a Changelog since it is quite popular and I don't want to introduce "fragmentation" just because of breaking changes indicator. But I certainly understand your effort.

I think it is critical to officially incorporate a breaking changes indicator to the Keep a Changelog anyway. This issue has been opened since 2014 and as the time passes, it seems to be more and more important. What options do we have for this issue to get some deserved momentum? What are the reasons against including a breaking changes indicator?

---

@majormoses I have noticed that your Keep a Changelog flavor uses the <version> - <date> format for a release title. I would like to hear your opinion on the release title format in the issue #204.

[majormoses]

Your flavor looks great but I would rather stay with Keep a Changelog since it is quite popular and I don't want to introduce "fragmentation" just because of breaking changes indicator. But I certainly understand your effort.

I think it is critical to officially incorporate a breaking changes indicator to the Keep a Changelog anyway. This issue has been opened since 2014 and as the time passes, it seems to be more and more important. What options do we have for this issue to get some deserved momentum? What are the reasons against including a breaking changes indicator?

Completely understand, the beauty of open source is that we (collectively and individually) can do what makes the most sense for our projects/communities. I view keep a changelog very much like the "pirates code" they are more guidelines than rules. I would obviously prefer to to enhance the guidelines and follow a more "vanilla" flavor but due to lack of consensus it does not look like it will be added any time soon. I don't see much of an issue to extend the guidelines for your project/community as it makes sense in the meantime or following my flavor but I understand the fragmentation argument. My flavor enhancements are very much inline with the spirit of what keep a changelog, "To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project.". It does not contain anything that breaks backwards compatibility, it's just a header that someone can choose to leverage.

I think everyone here agrees on adding this its a think more of a debate at this point of what that looks like. I personally would prefer breaking changes to become a first class header. At this point I have invested too much into doing it the way I prefer that even should we settle on tags or bold which are not as noticeable, meaningful, or searchable as a header that I would probably still maintain my own flavor changes which ironically would introduce real fragmentation and a fork of the guidelines. I think at this point it's purely opinion and no one is right or wrong. Perhaps the best solution would be to encourage maintainers to choose what makes sense for their project/community and offer the two "common" or "accepted" options officially as part of the spec.

have noticed that your Keep a Changelog flavor uses the <version> - <date> format for a release title. I would like to hear your opinion on the release title format in the issue #204

Honestly that was something I just inherited and have not really looked into it much tbh, when I have some time this weekend I can take a closer look.

[dominiksalvet]

I personally would prefer breaking changes to become a first class header.

@majormoses Actually I don't know what you mean by "first class header". H1 is out of option as it is the "Changelog" title. Maybe you meant that a breaking changes section should be listed first of all types of changes, am I right? That would be reasonable for developers depending on a project but I am not sure whether everybody would be satisfied enough with it. However - as I think about it - not only developers are interested in breaking changes. Practically everyone who uses the project's API might be interested in those changes.

Anyway, I found myself sorting the sections by their alphabetical order some time ago as it is much easier to remember. Coincidentally, it is a near match to what is stated on the Keep a Changelog website except for Removed and Fixed sections being exchanged. Unfortunately, my sorting wouldn't make Breaking changes to be the first section of all but that's just my problem.

At this point, I agree on encouraging maintainers. Please could you inform them about this issue somehow?

[majormoses]

@majormoses Actually I don't know what you mean by "first class header". H1 is out of option as it is the "Changelog" title. Maybe you meant that a breaking changes section should be listed first of all types of changes, am I right? That would be reasonable for developers depending on a project but I am not sure whether everybody would be satisfied enough with it. However - as I think about it - not only developers are interested in breaking changes. Practically everyone who uses the project's API might be interested in those changes.

Ya sorry I was not clear. As you guessed I meant that it should be listed as a header type.

Anyway, I found myself sorting the sections by their alphabetical order some time ago as it is much easier to remember.

Makes sense I don't think its really all that important spec wise to agree on that as I think it probably depends on preference. I polled my community on this and generally the feedback was alphabetized was not important. As a consumer what do I care about is how this affects me. What we found was people wanted in the following order:

1. Breaking Changes: as this have the highest impact we want these first
2. Security: you should care about security even if you dont 😉
3. Fixed: what bugs might I be facing that entices me to pull in new version
4. Added: what new features might entice me to pull in new version
5. Deprecated: what should I know about but don't have to change immediately to leverage
6. Changed: this is kind of the catch all
7. Removed we rarely use this as we have Breaking Changes, the only time we use this are for things like removing testing for versions of language/platform x, it does not mean we removed compatibility (as that is a breaking change) but we are removing it as a supported and tested version where going forward it will be best effort support.

I won't claim I always follow that but I try to when I can. Again this is focus on the human vs machine consumers, we already have git log for machines.

At this point, I agree on encouraging maintainers. Please could you inform them about this issue somehow?

@olivierlacan can you weigh in? I would really like to see something move forward and I don't see why we can't support both use cases. At the end of the day these are guidelines.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

[Mouvedia]

it is good to note that not all breaking changes are actually Changes

That's up for debate. I can see myself using Fixed depending on my interpretation and the motivation behind the change.

[dominiksalvet]

@Mouvedia Actually I think that your case, the Fixed section, is not that much for a debate. I admit that Fixed may introduce breaking changes but they are inevitable in the long term. As opposed to, e.g., the Removed section, in which case a program is usually in the correct state before and also after making the change, the Fixed section is different. The program is not in the correct state before and should be in the correct state after making a Fixed change (from Keep a Changelog: Fixed for any bug fixes). What I am trying to say is that sometimes the Fixed section changes a program's behaviour in an incompatible way (i.e., makes a breaking change) but this change is usually expected by users of this program because it is a bug and so it might not be so much a breaking change indeed.

Anyway, take a closer look at my reply to @majormoses:

You made a good point about the individual section for breaking changes as for quickly identify breaking changes, which in case of per-item could be a little tricky - namely for longer version changelogs. Also, I must admit that if we would use per-item indicator, it could steal users attention (not only the programmers depending on a project) from, e.g., new features or changes made in a compatible way that are not highlighted/prefix with something like BREAKING, which could be shame.

Well, I guess you have convinced me with your arguments. Also, you are right that breaking changes are so important for some developer that they should be in its own section. I was stuck in the Changed -> Breaking changes, Remove -> ???, New -> ???, etc. analogy.

In the end, everything we do during software development is that we are changing it. Even adding or removing things are still changes. What is ahead of us is to choose which categories of changes are important for Changelogs readers and I encourage that a Breaking changes category should be among them.

[dominiksalvet]

@olivierlacan Okay, so more and more I tend to use just plain Breaking title for all breaking changes. Can we reach any consensus based on mentioned proposals? It would be great to see breaking changes incorporated officially into Keep a Changelog project. 🚀

[e-g-hategan]

I think the lack of consensus around this is because of the conflicting requirements of semver which was designed (mostly) for machine consumption and changelogs which are mostly for human consumption.

As far as I can tell, not all but most changelog types of changes can be any of:

• incompatible API changes
• functionality in a backwards compatible manner
• backwards compatible fixes

A different approach to what has been already mentioned is to introduce another level of indentation:

• Major / Incompatible / Breaking Changes
• Minor / Features
• Patch / Fixes

## [Unreleased]
### Breaking Changes
#### Removed
- Backwards incompatible removal.
- Backwards incompatible removal.
#### Changed
- Backwards incompatible change.
### Features
#### Added
- Backwards compatible addition.
- Backwards compatible addition.
- Backwards compatible addition.
#### Changed
- Backwards compatible change.
### Fixes
#### Deprecated
- Backwards compatible deprecations.
#### Security
- Backwards compatible security fix.
#### Fixed
- Backwards compatible bugfix.
- Backwards compatible bugfix.

This would also work for yanked releases.

[mvz]

@e-g-hategan I think you are on to something regarding the lack of consensus. You are right that some humans want to produce or consume changelogs with Removed/Added/Changed sections, cross-cutting the semver categories.

I for one am not interested in thinking about Removed/Added/Changed when I read changelogs, so having only semver-related categories would be fine for me.

I actually do not agree that semver is mainly for computers: Computers do not care about features or bug fixes. It is true that semver allows better tooling so computers can do automated updates. But that is only half the story.

[kyeotic]

Since breaking changes can only go under prerelease versions or major versions I think its common that more than one will appear on any given release. Libraries tend to save up their breaking changes so that they can increment the major version a single time for several breaking changes.

Given that, and given that there is some consensus that with several independent breaking changes though it gets real ugly to show BREAKING before each line.

Changed

• BREAKING: did some stuff
• BREAKING: did some things
• BREAKING: broke your fav api
• BREAKING: renamed a bunch of props
• BREAKING: thing now only accepts boolean arguments

---

It's even harder to see when those changes are broken up across several sections, even if they are at the top of those sections. Example

Changed

• BREAKING: did some stuff
• BREAKING: did some things
• BREAKING: renamed a bunch of props
• made a minor change to rendering performance on doBetter

Added

• BREAKING: validate now requires a 3rd parameter
• options added to stuff
• new exported function awesome

Removed

• BREAKING: removed your second favorite API

---

Again, breaking changes are only possible when using SemVer on major releases or prereleases. They come in batches. Finally, they are generally the most important part of any versions release notes. So I think they deserve their own section/header. Humans want to see them grouped together, and called out as much as possible (while staying within the general formatting of this spec). Example:

Breaking Changes

• did some stuff
• did some things
• renamed a bunch of props
• validate now requires a 3rd parameter
• removed your second favorite API

Changed

• made a minor change to rendering performance on doBetter

Added

• options added to stuff
• new exported function awesome

[Almenon]

To summarize the positives and negatives for both sides:

inline breaking:

+ Allows you to categorize breaking changes in the appropriate section (ex: CHANGED, SECURITY, or FIXED)

+ It takes up less room

- you have to type breaking before each break

- Some argue it's not as recognizable as a seperate header

- There is precedent for different header types already, but no precedent for inline headers. It would make the schema (and any associated parsers) more complex.

Example:

Changed

• Breaking: Remove AMQP result backend (#6360).
• Warn when deprecated settings are used (#6353).
• Expose retry_policy for Redis result backend (#6330).
• Prepare Celery to support the yet to be released Python 3.9 (#6328).

---

header breaking:

+ Some argue it's more recognizable

+ Faster to type

- takes up more room

+ There is already precedent for different header types. Adding a new header would be a very simple change to the schema and schema parsers.

- uncategorized. Is it a security, fix, or a change? Who knows?

- might be confusion as to where to put a breaking change. Would it go under "CHANGED", "CHANGED" and "BREAKING CHANGE", or just "BREAKING CHANGE"?

Example:

Breaking Changes

• Remove AMQP result backend (#6360).

Changed

• Warn when deprecated settings are used (#6353).
• Expose retry_policy for Redis result backend (#6330).
• Prepare Celery to support the yet to be released Python 3.9 (#6328).

---

There's a few more options, like adding both header and inline, but the most popular seems to be the above two. Any arguments for/against the above two that I'm missing here?

[mricherzhagen]

Another option for inline change-"severity"-classification might be to use Emoji. They don't take up a lot of space, but can convey a lot of information.

Denote breaking changes with 💣 or ⚡ or 💥

or

Denote all changes according to their version-bump-requirement (patch minor major):

• 🥉 🥈 🥇
• 🟡 🟠 🔴 (Colors are bad, though. Not colorblind-friendly. Please don't use these)
• ▪ ◼ ⬛
• 🔈 🔉 🔊
• 💧 💦 🌊
• ➡️ ↗ ⬆
• ❕❗‼
• → ⇉ ⇶ (Sadly no triple up arrow for vertical 😢 )
• 🕯️ 💡 🌞 or ☀

I think my favorites are the 🌊, ⬆ and ‼ set. The benefit of denoting all changes with a "class" is, that Emoji tend to have uniform width, so the change descriptions in the changelog stay left aligned.

My background is, that I want to use a tool to gather the changes and record the required version bump for each change, but don't want to loose that information when all the changes are baked into a Changelog file (tool doesn't support recording that information yet, though).

[rcdailey]

I also agree breaking changes deserve their own section. One good reason is upgrade notes. I may want to include fenced code blocks to show examples of before/after configurations, how I expect things to change based on what is breaking, etc. I can't do all of that in a single bullet point lost with other changes that need not be so verbose.