The terms MAJOR.MINOR.PATCH are not semantic #439

New Issue

GiteaMirror · 2026-02-17T12:05:14-06:00

GiteaMirror commented

2026-02-17 12:05:14 -06:00

Originally created by @davidbarratt on GitHub (Oct 12, 2020).

Problem
Semver uses the historically significant terms MAJOR.MINOR.PATCH. While these terms are intuitive, they are not semantic. I have noticed that maintainers think (incorrectly?) that the terms relate to the amount of change to the code or the API which is inconsistent with semver. For instance, a maintainer may refactor their entire library, but not change the public API in anyway. According to semver, this would be a PATCH change, even though the entire library was rewritten. This introduces a lot of unnecssary confusion.

Proposed Solution
Rename MAJOR.MINOR.PATCH to BREAKING.FEATURE.FIX which is a more semantic represenation of the version string.

Originally created by @davidbarratt on GitHub (Oct 12, 2020). **Problem** Semver uses the historically significant terms `MAJOR.MINOR.PATCH`. While these terms are intuitive, they are not semantic. I have noticed that maintainers think (incorrectly?) that the terms relate to the _amount_ of change to the code or the API which is inconsistent with semver. For instance, a maintainer may refactor their entire library, but not change the public API in anyway. According to semver, this would be a `PATCH` change, even though the entire library was rewritten. This introduces a lot of unnecssary confusion. **Proposed Solution** Rename `MAJOR.MINOR.PATCH` to `BREAKING.FEATURE.FIX` which is a more semantic represenation of the version string.

GiteaMirror added the consensus seeking label 2026-02-17 12:05:14 -06:00

GiteaMirror commented

2026-02-17 12:05:15 -06:00

@ghost commented on GitHub (Oct 25, 2020):

If a maintainer refactors their entire library, wouldn't that mean that they had also refactored the public API's code in some way? I think that your proposed BREAKING.FEATURE.FIX is way more intuitive and in line with the definitions given for MAJOR, MINOR, and PATCH. I think the definitions are much more a problem than the terms themselves.

@ghost commented on GitHub (Oct 25, 2020): If a maintainer refactors their entire library, wouldn't that mean that they had also refactored the public API's code in some way? I think that your proposed `BREAKING.FEATURE.FIX` is way more intuitive and in line with the definitions given for MAJOR, MINOR, and PATCH. I think the definitions are much more a problem than the terms themselves.

GiteaMirror commented

2026-02-17 12:05:15 -06:00

@davidbarratt commented on GitHub (Oct 25, 2020):

If a maintainer refactors their entire library, wouldn't that mean that they had also refactored the public API's code in some way?

Not necessarily, take a library that is at 1.0.0 and looks somethign like this:

class FooBar {
  public function getFooBar() {
    // 1,000 lines of code.
  }
}

Let's say you as a maintainer decide that this is a lot of code in a single method, so you refactor it to be much smaller like:

class FooBar {
  public function getFooBar() {
    // 10 lines of code.
  }

  private function getFoo() {
   // 100 lines of code
  }

 private function getBar() {
   // 100 lines of code
  }

  // 8 other methods with 100 lines each
}

In the process of doing this, you realize you can simplify a lot of the variable names (since they are now scoped to the smaller methods). You're very happy with your work, even though git reports that you've changed almost every line

Now comes time to version it..... according to semver, this would be 1.0.1

I have seen maintainers protest with things like:

But this is a major change! I basically rewrote the whole thing!

Well yes, you did, but you didn't break the public API, so this is a PATCH

But I changed so much! I may have broken something!

I think may is the keyword here. Any change in software may have broken something, that doesn't mean you intentionally borke something.

The reality is, is that semver doesn't communicate what has changed or how much has changed, but rather how the changes affect the user. I think the biggest problem with semver, is maintainers pretending to follow semver. Changing the names would go a long way to clearly communicating the intention and meaning behind each number.

@davidbarratt commented on GitHub (Oct 25, 2020): > If a maintainer refactors their entire library, wouldn't that mean that they had also refactored the public API's code in some way? Not necessarily, take a library that is at `1.0.0` and looks somethign like this: ```php class FooBar { public function getFooBar() { // 1,000 lines of code. } } ``` Let's say you as a maintainer decide that this is a lot of code in a single method, so you refactor it to be much smaller like: ```php class FooBar { public function getFooBar() { // 10 lines of code. } private function getFoo() { // 100 lines of code } private function getBar() { // 100 lines of code } // 8 other methods with 100 lines each } ``` In the process of doing this, you realize you can simplify a lot of the variable names (since they are now scoped to the smaller methods). You're very happy with your work, even though git reports that you've changed almost every line Now comes time to version it..... according to semver, this would be `1.0.1` I have seen maintainers protest with things like: > But this is a **major** change! I basically rewrote the whole thing! Well yes, you did, but you didn't break the public API, so this is a PATCH > But I changed so much! I may have broken something! I think _may_ is the keyword here. Any change in software _may_ have broken something, that doesn't mean you _intentionally_ borke something. -------- The reality is, is that semver doesn't communicate _what_ has changed or _how much_ has changed, but rather how the changes _affect the user_. I think the biggest problem with semver, is maintainers _pretending_ to follow semver. Changing the names would go a long way to clearly communicating the intention and meaning behind each number.

GiteaMirror commented

2026-02-17 12:05:16 -06:00

@ghost commented on GitHub (Oct 25, 2020):

Thanks for clarifying.

Unfortunately, #588 may invalidate your proposal since it involves a definition update, where the discussion around updating the definitions of MAJOR, MINOR, and PATCH is to make them more abstract than the proposed changes in the PR right now.

I think the biggest problem with semver, is maintainers pretending to follow semver.

Yeah, I tend to agree with you on this one.

@ghost commented on GitHub (Oct 25, 2020): Thanks for clarifying. Unfortunately, #588 may invalidate your proposal since it involves a definition update, where the discussion around updating the definitions of MAJOR, MINOR, and PATCH is to make them more abstract than the proposed changes in the PR right now. > I think the biggest problem with semver, is maintainers pretending to follow semver. Yeah, I tend to agree with you on this one.

GiteaMirror commented

2026-02-17 12:05:17 -06:00

@davidbarratt commented on GitHub (Oct 25, 2020):

Unfortunately, #588 may invalidate your proposal since it involves a definition update, where the discussion around updating the definitions of MAJOR, MINOR, and PATCH is to make them more abstract than the proposed changes in the PR right now.

If I'm reading the issue correctly, it doesn't invalidate what I'm asking for, but instead affirms it. Perhaps my proposed solution needs some modification because, no, it's not a FIX necessarily it could be any CHANGE that isn't one of the other two. I'm open to more descriptive terms. Ultimately the terminology used should be as descriptive as possible. What we have now implies things about semver that isn't the case.

@davidbarratt commented on GitHub (Oct 25, 2020): > Unfortunately, #588 may invalidate your proposal since it involves a definition update, where the discussion around updating the definitions of MAJOR, MINOR, and PATCH is to make them more abstract than the proposed changes in the PR right now. If I'm reading the issue correctly, it doesn't invalidate what I'm asking for, but instead _affirms_ it. Perhaps my proposed solution needs some modification because, no, it's not a `FIX` necessarily it could be any `CHANGE` that isn't one of the other two. I'm open to more descriptive terms. Ultimately the terminology used should be as descriptive as possible. What we have now implies things about semver that isn't the case.

GiteaMirror commented

2026-02-17 12:05:18 -06:00

@ghost commented on GitHub (Oct 25, 2020):

Yes, you are right. I was confused between API changes and non-API changes, but after re-reading the SemVer spec, your proposal makes total sense.

I think your original proposal for BREAKING.FEATURE.FIX is completely sufficient.

@ghost commented on GitHub (Oct 25, 2020): Yes, you are right. I was confused between API changes and non-API changes, but after re-reading the SemVer spec, your proposal makes total sense. I think your original proposal for `BREAKING.FEATURE.FIX` is completely sufficient.

GiteaMirror commented

2026-02-17 12:05:18 -06:00

@magjac commented on GitHub (Oct 25, 2020):

An argument against making the terms semantic is that by having them non-semantic, people are forced to read the semver spec to find out what they mean. Too many people have opinions about what they think the terms mean without actually reading the spec. I think it would be hard find semantic terms that are enough succint since they would need to be something like BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE.

@magjac commented on GitHub (Oct 25, 2020): An argument against making the terms semantic is that by having them non-semantic, people are *forced* to read the semver spec to find out what they mean. Too many people have opinions about what they *think* the terms mean without actually reading the spec. I think it would be hard find semantic terms that are enough succint since they would need to be something like BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE.

GiteaMirror commented

2026-02-17 12:05:19 -06:00

@Tieske commented on GitHub (Oct 25, 2020):

referring to my comment earlier today, I think there should be a clear distinction between the first 2 components, and the 3rd, because the first 2 are a functionality compatibility promises, and the last is not, it's just an improvement (could be any thing).

So the last element could simply be "IMPROVEMENT".

The problem with BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE is that a MAJOR increment is not necessarily a breaking change. You MUST increment if it is breaking, but nothing prevents you from incrementing it if you make a non-breaking change (and that is quite common). Preventing that, is not part of the spec, the spec is about backward compatibility promises.

@Tieske commented on GitHub (Oct 25, 2020): referring to my [comment earlier today](https://github.com/semver/semver/pull/588#issuecomment-716149752), I think there should be a clear distinction between the first 2 components, and the 3rd, because the first 2 are a functionality compatibility promises, and the last is not, it's just an improvement (could be any thing). So the last element could simply be "IMPROVEMENT". The problem with BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE is that a MAJOR increment is not necessarily a breaking change. You MUST increment if it is breaking, but nothing prevents you from incrementing it if you make a non-breaking change (and that is quite common). Preventing that, is not part of the spec, the spec is about backward compatibility promises.

GiteaMirror commented

2026-02-17 12:05:20 -06:00

@davidbarratt commented on GitHub (Oct 25, 2020):

An argument against making the terms semantic is that by having them non-semantic, people are forced to read the semver spec to find out what they mean. Too many people have opinions about what they think the terms mean without actually reading the spec.

People aren't forced to do anything. I would highly recommend the book Don't Make Me Think which goes to great length to explain that people (users) do not read. They do not read buttons, menus, text, or anything we put in front of them. Expecting them to read something is a futal effort. Therefore, everything should be as simple and plain as possible.

@davidbarratt commented on GitHub (Oct 25, 2020): > An argument against making the terms semantic is that by having them non-semantic, people are _forced_ to read the semver spec to find out what they mean. Too many people have opinions about what they _think_ the terms mean without actually reading the spec. People aren't _forced_ to do anything. I would highly recommend the book _[Don't Make Me Think](https://en.wikipedia.org/wiki/Don%27t_Make_Me_Think)_ which goes to great length to explain that people (users) do not read. They do not read buttons, menus, text, or anything we put in front of them. Expecting them to read something is a futal effort. Therefore, everything should be as simple and plain as possible.

GiteaMirror commented

2026-02-17 12:05:21 -06:00

@davidbarratt commented on GitHub (Oct 25, 2020):

@Tieske How about BREAKING.FEATURE.IMPROVEMENT ?

@davidbarratt commented on GitHub (Oct 25, 2020): @Tieske How about `BREAKING.FEATURE.IMPROVEMENT` ?

GiteaMirror commented

2026-02-17 12:05:21 -06:00

@Tieske commented on GitHub (Oct 26, 2020):

FEATURE = ADDITION ?

But also still wondering whether it should deviate from industry standard "major.minor.patch"...

@Tieske commented on GitHub (Oct 26, 2020): FEATURE = ADDITION ? But also still wondering whether it should deviate from industry standard "major.minor.patch"...

GiteaMirror commented

2026-02-17 12:05:22 -06:00

@gedankenexperimenter commented on GitHub (Mar 25, 2021):

Since the MINOR version number is required to change not only when a new (backwards-compatible) feature is added, but also when a part of the API is deprecated, it might make more sense to use the words INCOMPATIBLE, COMPATIBLE, and FIX.

@gedankenexperimenter commented on GitHub (Mar 25, 2021): Since the `MINOR` version number is required to change not only when a new (backwards-compatible) _feature_ is added, but also when a part of the API is _deprecated_, it might make more sense to use the words `INCOMPATIBLE`, `COMPATIBLE`, and `FIX`.

GiteaMirror commented

2026-02-17 12:05:23 -06:00

@jwdonahue commented on GitHub (Sep 6, 2021):

I like the current labels precisely because they are semantically correct. The spec defines an abstraction on top of previous abstractions. Names are nothing at all if not at least semantic. We are talking about language yes?

The field names are derived from common pre-semver terminology of the syntax in use at the time. The spec provided semantic overlay on top of the syntax and within the previous semantics. There are other semantic overlays that could also be applied, some of which would be technically conforming to SemVer. Many of the tools that support SemVer, also support non-complaint uses of the Major.Minor.Patch version triple. In fact, the spec was originally written such that we could use existing pre-existing tools in SemVer compliant ways. Most of those tools understand major, minor and patch in terms of Major > Minor > Patch, where > should be read as "greater or more inclusive than".

In other words, most of the tooling around SemVer, does not understand breaking or non-breaking, much less features or fixes. That isn't to say that tools with more modern roots don't. I am merely pointing out that the Major, Minor and Patch terminology are well known place holders for the most common version string format, that carry less constrained semantics. One can't argue that a breaking change is not a major change. One might argue that adding one or more features may or may not be minor, so the spec requires at least a minor bump for these, but allows us to issue a major bump. Similarly, a bug fix falls within the meaning of patch, but the later includes refinements in documentation or other changes that are not strictly fixes.

The current labels make sense because:

Not all major changes are breaking changes, but breaking changes are major changes.
Not all minor changes are new features, but new features are usually minor changes..
Not all patch changes are bug fixes, but all bug fixes are patch level changes.

The spec specifies A must be bumped if B, but does not rule out all the other things we always used A for. I argue that if you are going to change these labels, you might as well come up with a better standard all around, but the path to designing, implementing and adoption of the later, is long and full of pitfalls.

@jwdonahue commented on GitHub (Sep 6, 2021): I like the current labels precisely because they are semantically correct. The spec defines an abstraction on top of previous abstractions. Names are nothing at all if not at least semantic. We are talking about language yes? The field names are derived from common pre-semver terminology of the syntax in use at the time. The spec provided semantic overlay on top of the syntax and within the previous semantics. There are other semantic overlays that could also be applied, some of which would be technically conforming to SemVer. Many of the tools that support SemVer, also support non-complaint uses of the Major.Minor.Patch version triple. In fact, the spec was originally written such that we could use existing pre-existing tools in SemVer compliant ways. Most of those tools understand major, minor and patch in terms of Major > Minor > Patch, where `>` should be read as "greater or more inclusive than". In other words, most of the tooling around SemVer, does not understand breaking or non-breaking, much less features or fixes. That isn't to say that tools with more modern roots don't. I am merely pointing out that the Major, Minor and Patch terminology are well known place holders for the most common version string format, that carry less constrained semantics. One can't argue that a breaking change is not a major change. One might argue that adding one or more features may or may not be minor, so the spec requires at least a minor bump for these, but allows us to issue a major bump. Similarly, a bug fix falls within the meaning of patch, but the later includes refinements in documentation or other changes that are not strictly fixes. The current labels make sense because: - Not all major changes are breaking changes, but breaking changes are major changes. - Not all minor changes are new features, but new features are usually minor changes.. - Not all patch changes are bug fixes, but all bug fixes are patch level changes. The spec specifies `A must be bumped if B`, but does not rule out all the other things we always used A for. I argue that if you are going to change these labels, you might as well come up with a better standard all around, but the path to designing, implementing and adoption of the later, is long and full of pitfalls.

GiteaMirror commented

2026-02-17 12:05:23 -06:00

@jwdonahue commented on GitHub (Sep 6, 2021):

@davidbarratt

I have noticed that maintainers think (incorrectly?) that the terms relate to the amount of change to the code or the API which is inconsistent with semver

Not necessarily inconsistent. Big changes can result in major or minor bumps, even if they are just bug fixes or changes in documentation. The spec uses the word MUST in a lot of places, but those don't completely define the semantics. There is much which is necessarily implied, because any attempt to be more explicit would tend to over-constrain the specification.

The history of the version triple really began with a compromise between marketing, engineering and support. The marketers wanted a marketing label that was distinct from their brand, but engineering and support needed more precision. This was before the days when code reuse was anywhere near as popular as it is today and the main purpose of the version number was to identify a specific revision of a product, where v0 < v1 < v2.

This introduces a lot of unnecssary confusion.

While these terms are intuitive, they are not semantic.

So they are intuitive, confusing and not semantic? Where to begin?

They are not neutral labels or names, they do have meaning in common English and more specifically, in areas of engineering and software.

I argue that you have not shown that the current labelling scheme is the cause of said confusion. Even if it turned out to be a more popular set of labels in the long run, I am not convinced that it would reduce the levels of confusion over the spec in general. As a committed deconfuser in this area, I prefer to reserve as much of my native language as possible, for the purposes of explaining the nuances of semantic versioning.

Contemplating new labels for the purpose of deconfusing people, I think HR.MR.LR would be the best field labels, where:

HR == High Risk
MR == Medium Risk
LR == Low Risk

Because risk really is what SemVer is meant to convey and they don't have the traditional interpretations applied to Major == big, Minor == small, Patch == tiny. My views regarding various proposals for label changes in the spec have evolved over the years. I don't recall evidence of any real confusion surrounding the labels themselves. The spec uses them to define its semantics and in fact, big/major/breaking are all mostly conflated with each other, which implies that the intent and the letter of the spec seem to be interpreted reasonably well. In other words, I don't think that, in and of itself is a confusion.

We do get a lot of folks here and on Stack Overflow who are trying to settle a debate going on between various team members, regarding one aspect of SemVer or another. These are usually focused on application of the semantics to specific cases; such as does a refactoring require a patch, minor or major version bump (one of the most common). Well a strict first reading of the spec suggests it's a patch level change, but a deeper understanding of the potential impacts of any specific refactoring on your customers, might warrant a minor or major bump. If I had to describe that, strictly in terms of fix, feature or breaking bump, it might not make any sense at all! But based on risk, I can say that depending on your ecosystem; an improvement in performance, resulting from a refactoring, might require a minor bump, and a resulting degradation of performance would likely require a major bump, and I don't sound like a confused blabbering idiot. The extra abstraction layer I get from a well chosen label, allows me to describe precisely what I mean, without having to overload any of the terms.

I think most people read the spec once and think they understand it. But most people really aren't trained to read and understand standards language, even if they read it twice or ten times. It requires more than a colloquial understanding of the English language. You need formal logic and time to think through the implications of the spec, to grasp their full flavor and meaning. It is provably impossible to describe any system, strictly in its own terms. We have to use referential language and abstractions that are not system specific to accurately describe the system itself. Most folks, just want to understand enough that they can use their tools. Semantic versioning is a means to an end, and they have more important things to wrap their heads around, so there's always a certain level of confusion out there, whether the confused know it or not.

So if I were to get behind a change in the labels used in the spec, I would want it to at least marginally improve the efficiency of describing the nuances, in terms that someone with near zero time available, can grasp. The shorter, two character labels meet that requirement and the hint they provide wrt level of risk to consumers would be a bonus.

@jwdonahue commented on GitHub (Sep 6, 2021): @davidbarratt > I have noticed that maintainers think (incorrectly?) that the terms relate to the amount of change to the code or the API which is inconsistent with semver Not necessarily inconsistent. Big changes can result in major or minor bumps, even if they are just bug fixes or changes in documentation. The spec uses the word `MUST` in a lot of places, but those don't completely define the semantics. There is much which is necessarily implied, because any attempt to be more explicit would tend to over-constrain the specification. The history of the version triple really began with a compromise between marketing, engineering and support. The marketers wanted a marketing label that was distinct from their brand, but engineering and support needed more precision. This was before the days when code reuse was anywhere near as popular as it is today and the main purpose of the version number was to identify a specific revision of a product, where v0 < v1 < v2. ----- > This introduces a lot of unnecssary confusion. > While these terms are intuitive, they are not semantic. So they are intuitive, confusing and not semantic? Where to begin? They are not neutral labels or names, they do have meaning in common English and more specifically, in areas of engineering and software. I argue that you have not shown that the current labelling scheme is the cause of said confusion. Even if it turned out to be a more popular set of labels in the long run, I am not convinced that it would reduce the levels of confusion over the spec in general. As a committed deconfuser in this area, I prefer to reserve as much of my native language as possible, for the purposes of explaining the nuances of semantic versioning. Contemplating new labels for the purpose of deconfusing people, I think HR.MR.LR would be the best field labels, where: - HR == High Risk - MR == Medium Risk - LR == Low Risk Because risk really is what SemVer is meant to convey and they don't have the traditional interpretations applied to Major == big, Minor == small, Patch == tiny. My views regarding various proposals for label changes in the spec have evolved over the years. I don't recall evidence of any real confusion surrounding the labels themselves. The spec uses them to define its semantics and in fact, big/major/breaking are all mostly conflated with each other, which implies that the intent and the letter of the spec seem to be interpreted reasonably well. In other words, I don't think that, in and of itself is a confusion. We do get a lot of folks here and on Stack Overflow who are trying to settle a debate going on between various team members, regarding one aspect of SemVer or another. These are usually focused on application of the semantics to specific cases; such as does a refactoring require a patch, minor or major version bump (one of the most common). Well a strict _first reading_ of the spec suggests it's a patch level change, but a deeper understanding of the potential impacts of any _specific_ refactoring on your customers, might warrant a minor or major bump. If I had to describe that, strictly in terms of fix, feature or breaking bump, it might not make any sense at all! But based on risk, I can say that depending on your ecosystem; an improvement in performance, resulting from a refactoring, might require a minor bump, and a resulting degradation of performance would likely require a major bump, and I don't sound like a confused blabbering idiot. The extra abstraction layer I get from a well chosen label, allows me to describe precisely what I mean, without having to overload any of the terms. I think most people read the spec once and think they understand it. But most people really aren't trained to read and understand standards language, even if they read it twice or ten times. It requires more than a colloquial understanding of the English language. You need formal logic and time to think through the implications of the spec, to grasp their full flavor and meaning. It is provably impossible to describe any system, strictly in its own terms. We have to use referential language and abstractions that are not system specific to accurately describe the system itself. Most folks, just want to understand enough that they can use their tools. Semantic versioning is a means to an end, and they have more important things to wrap their heads around, so there's always a certain level of confusion out there, whether the confused know it or not. So if I were to get behind a change in the labels used in the spec, I would want it to at least marginally improve the efficiency of describing the nuances, in terms that someone with near zero time available, can grasp. The shorter, two character labels meet that requirement and the hint they provide wrt level of risk to consumers would be a bonus.

GiteaMirror commented

2026-02-17 12:05:24 -06:00

@jwdonahue commented on GitHub (Sep 6, 2021):

For instance, a maintainer may refactor their entire library, but not change the public API in anyway. According to semver, this would be a PATCH change, even though the entire library was rewritten. This introduces a lot of unnecssary confusion.

This is factually incorrect. A refactoring MAY be a patch level change, but it MAY also be minor or major. Consider that most refactorings have performance impacts that might range from I/O and memory usage patterns to changes in CPU usage. In some ecosystems, a degradation in performance is considered a breaking change and an improvement is often considered a feature. Even well tested minor refactorings represent risk potentials that could exceed patch level version bumps.

What is the risk in a performance improvement? Consider a tool (T) that uses library L1 to process a queue of documents. T pushes results to another queue that processes those results. The system is tuned to handle 100% of the documents about 80% of the time and any unprocessed documents are dropped in the bit bucket. The sys-admins automatically update to latest patch level of T in order to streamline ingestion of security/bug fixes. If T's publisher refactors it to perform twice as fast, the above systems configuration will not be optimally tuned. It could start dropping more documents in the bit bucket and important information might be lost. Basically the effective total queue depth is now very close to the depth of T's output queue, not both combined.

If the publisher had bumped the minor version, then the admins wouldn't have ingested the change automagically, and they would have had time to evaluate the impacts of the changes on their system.

The spec says "MUST bump patch", but also leaves rolling it over to minor or major as an option.

@jwdonahue commented on GitHub (Sep 6, 2021): > For instance, a maintainer may refactor their entire library, but not change the public API in anyway. According to semver, this would be a PATCH change, even though the entire library was rewritten. This introduces a lot of unnecssary confusion. This is factually incorrect. A refactoring MAY be a patch level change, but it MAY also be minor or major. Consider that most refactorings have performance impacts that might range from I/O and memory usage patterns to changes in CPU usage. In some ecosystems, a degradation in performance is considered a breaking change and an improvement is often considered a feature. Even well tested minor refactorings represent risk potentials that could exceed patch level version bumps. What is the risk in a performance improvement? Consider a tool (T) that uses library L1 to process a queue of documents. T pushes results to another queue that processes those results. The system is tuned to handle 100% of the documents about 80% of the time and any unprocessed documents are dropped in the bit bucket. The sys-admins automatically update to latest patch level of T in order to streamline ingestion of security/bug fixes. If T's publisher refactors it to perform twice as fast, the above systems configuration will not be optimally tuned. It could start dropping more documents in the bit bucket and important information might be lost. Basically the effective total queue depth is now very close to the depth of T's output queue, not both combined. If the publisher had bumped the minor version, then the admins wouldn't have ingested the change automagically, and they would have had time to evaluate the impacts of the changes on their system. The spec says "MUST bump patch", but also leaves rolling it over to minor or major as an option.

GiteaMirror commented

2026-02-17 12:05:25 -06:00

@EvanCarroll commented on GitHub (Oct 28, 2021):

The problem with BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE is that a MAJOR increment is not necessarily a breaking change. You MUST increment if it is breaking, but nothing prevents you from incrementing it if you make a non-breaking change (and that is quite common). Preventing that, is not part of the spec, the spec is about backward compatibility promises.

While true, this is really a blight that perverts the whole spec as it would allow you to just replace the MAJOR with the seconds-since-epoch and setting minor and patch to zero every time. I can't see the merit here in changing the name. You could still do the ugly and call everything a "BREAKING CHANGE", most every change is a breaking change if you squint hard enough and expect the broken pre-fix behavior (or were working around it).

@EvanCarroll commented on GitHub (Oct 28, 2021): > The problem with BREAKING_API_CHANGE.COMPATIBLE_API_CHANGE.NON_API_CHANGE is that a MAJOR increment is not necessarily a breaking change. You MUST increment if it is breaking, but nothing prevents you from incrementing it if you make a non-breaking change (and that is quite common). Preventing that, is not part of the spec, the spec is about backward compatibility promises. While true, this is really a blight that perverts the whole spec as it would allow you to just replace the MAJOR with the seconds-since-epoch and setting minor and patch to zero every time. I can't see the merit here in changing the name. You could still do the ugly and call everything a "BREAKING CHANGE", most every change is a breaking change if you squint hard enough and expect the broken pre-fix behavior (or were working around it).

GiteaMirror commented

2026-02-17 12:05:26 -06:00

@EvanCarroll commented on GitHub (Oct 28, 2021):

My opinion on this is that BREAKING.FEATURE.FIX is an all around improvement because that's how the tooling behaves anyway (like semantic-release).

It literally matches breaking -> major bump, feat -> minor bump, and fix -> patch bump. So if this convention is so strong tooling is adopting it it doesn't make sense for the working in the spec to deviate.

@EvanCarroll commented on GitHub (Oct 28, 2021): My opinion on this is that BREAKING.FEATURE.FIX is an all around improvement because that's how the tooling behaves anyway [(like semantic-release).](https://semantic-release.gitbook.io/semantic-release/) It literally matches breaking -> major bump, feat -> minor bump, and fix -> patch bump. So if this convention is so strong tooling is adopting it it doesn't make sense for the working in the spec to deviate.

GiteaMirror commented

2026-02-17 12:05:27 -06:00

@Tieske commented on GitHub (Nov 1, 2021):

@EvanCarroll that's how it is commonly used, but that is not correct. "MAJOR" basically defines a 'scope' within which minor and patch operate. BREAKING has an implicit reference to something else. it is BREAKING when compared to X. And commonly we use BREAKING compared to BREAKING - 1. But that's an implicit assumption.

I might have 3 concurrent versions out; first version 3.0.0, a month later I come up with 12.0.0, and yet another month later with 1.0.0. All I can tell is that 3, 12, and 1 have their own 'scope' of compatibility. But nothing necessarily is BREAKING. They might actually be compatible with each other afaikt, you just can't rely on it based on semver rules.

Hence I previously proposed "PROMISE"."ADDITIONAL_PROMISE"."IMPLEMENTATION". But that didn't get any traction.

@Tieske commented on GitHub (Nov 1, 2021): @EvanCarroll that's how it is commonly used, but that is not correct. "MAJOR" basically defines a 'scope' within which minor and patch operate. BREAKING has an implicit reference to something else. it is BREAKING when compared to X. And commonly we use BREAKING compared to BREAKING - 1. But that's an implicit assumption. I might have 3 concurrent versions out; first version 3.0.0, a month later I come up with 12.0.0, and yet another month later with 1.0.0. All I can tell is that 3, 12, and 1 have their own 'scope' of compatibility. But nothing necessarily is BREAKING. They might actually be compatible with each other afaikt, you just can't rely on it based on semver rules. Hence I previously proposed "PROMISE"."ADDITIONAL_PROMISE"."IMPLEMENTATION". But that didn't get any traction.

GiteaMirror commented

2026-02-17 12:05:27 -06:00

@EvanCarroll commented on GitHub (Nov 1, 2021):

@EvanCarroll that's how it is commonly used, but that is not correct. "MAJOR" basically defines a 'scope' within which minor and patch operate. BREAKING has an implicit reference to something else. it is BREAKING when compared to X. And commonly we use BREAKING compared to BREAKING - 1. But that's an implicit assumption.

That sounds like you made the up. The name "scope" isn't anywhere in the spec. It isn't assumed or an "implicit reference" it's explicit and it's in the the spec,

The spec says

MAJOR version when you make incompatible API changes,

An then,

Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version._

And also,

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented.

So to be clear unless you think "incompatable" and "breaking" are semantically different then I don't see any argument that calling "MAJOR" "BREAKING" is incorrect.

"PROMISE"."ADDITIONAL_PROMISE"."IMPLEMENTATION".

Your words are so watered down as to have no more meaning than MAJOR.MINOR.PATCH. Kind of reminds of this.

Not to mention it seems to beg the question what is "PROMISE" if not a "PROMISE" any change up to and including the highest severity of "BREAKING CHANGE" triggered the bump? And what is "ANOTHER PROMISE" if not any change up to but not including the severity of a "BREAKING CHANGE" triggered the bump. And what is "IMPLEMENTATION" if not a promise that no changes including "BREAKING CHANGES" but also other user-visable changes occurred? You basically have "PROMISE"."ADDITIONAL_PROMISE"."ANOTHER_PROMISE": except we want to describe the semantics of the promise/contract in the terms of the spec.

@EvanCarroll commented on GitHub (Nov 1, 2021): > @EvanCarroll that's how it is commonly used, but that is not correct. "MAJOR" basically defines a 'scope' within which minor and patch operate. BREAKING has an implicit reference to something else. it is BREAKING when compared to X. And commonly we use BREAKING compared to BREAKING - 1. But that's an implicit assumption. That sounds like you made the up. The name "scope" isn't anywhere in the spec. It isn't assumed or an "implicit reference" it's explicit and it's in the the spec, The spec says > MAJOR version when you make **incompatible API** changes, An then, > _Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and **backwards incompatible API changes increment the major version**.__ And also, > **Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.** It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented. So to be clear unless you think _"incompatable"_ and _"breaking"_ are semantically different then I don't see any argument that calling "MAJOR" "BREAKING" is incorrect. > "PROMISE"."ADDITIONAL_PROMISE"."IMPLEMENTATION". Your words are so watered down as to have no more meaning than `MAJOR.MINOR.PATCH`. [Kind of reminds of this](https://www.youtube.com/watch?v=h67k9eEw9AY). Not to mention it seems to beg the question what is "PROMISE" if not a "PROMISE" any change up to and including the highest severity of "BREAKING CHANGE" triggered the bump? And what is "ANOTHER PROMISE" if not any change up to but not including the severity of a "BREAKING CHANGE" triggered the bump. And what is "IMPLEMENTATION" if not a promise that no changes including "BREAKING CHANGES" but also other user-visable changes occurred? You basically have "PROMISE"."ADDITIONAL_PROMISE"."ANOTHER_PROMISE": except we want to describe the semantics of the promise/contract **in the terms of the spec**.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#439