[GH-ISSUE #475] Replacing "when" by "when and only when"? #2082

New Issue

GiteaMirror · 2026-04-20T10:01:02-05:00

GiteaMirror commented

2026-04-20 10:01:02 -05:00

Originally created by @patricekrakow on GitHub (Nov 5, 2018).
Original GitHub issue: https://github.com/semver/semver/issues/475

Let's take the 1st statement as an example:

[...] increment the MAJOR version when you make incompatible API changes [...]

It means that you can increment the MAJOR version even when/if you do NOT make incompatible changes! So, as a consumer of the public API of the package, if I see an increment of the MAJOR version, I do NOT know if I have to change my application or not? This is why I would prefer to see:

[...] increment the MAJOR version when and only when you make incompatible API changes [...]

What do you think? Does that make sense? Or is it on purpose that MAJOR version can be incremented without incompatible API changes?

Originally created by @patricekrakow on GitHub (Nov 5, 2018). Original GitHub issue: https://github.com/semver/semver/issues/475 Let's take the 1st statement as an example: > [...] increment the MAJOR version *when* you make incompatible API changes [...] It means that you **can** increment the MAJOR version *even when/if* you do **NOT** make incompatible changes! So, as a consumer of the public API of the package, if I see an increment of the MAJOR version, I do **NOT** know if I have to change my application or not? This is why I would prefer to see: > [...] increment the MAJOR version ***when and only when*** you make incompatible API changes [...] What do you think? Does that make sense? Or is it **on purpose** that MAJOR version can be incremented *without* incompatible API changes?

GiteaMirror added the consensus seeking spelling/grammar question waiting for PR labels 2026-04-20 10:01:02 -05:00

GiteaMirror closed this issue

2026-04-20 10:01:03 -05:00

GiteaMirror commented

2026-04-20 10:01:05 -05:00

@vladdeSV commented on GitHub (Nov 13, 2018):

I have also had these thoughts

@vladdeSV commented on GitHub (Nov 13, 2018): I have also had these thoughts

GiteaMirror commented

2026-04-20 10:01:06 -05:00

@jwdonahue commented on GitHub (Nov 25, 2018):

Then it might as well read never bump the major version number, because a breaking change for some is not a breaking change for all. A bump in the major version number literally translates into "I publish this with the suspicion that it might break a sufficient number of my clients builds as to be harmful to my reputation, therefore I bumped the major version number". It does not translate into "this release will break your build or application".

Yes, the current wording is quite deliberate. You should never assume that any change is breaking/non-breaking in every use case, particularly yours. It makes sense to run automated updates to preproduction test environments, based on patch releases and, depending on the publisher, minor changes. A human should review release notes prior to taking a minor release, in most cases, and always prior to deciding on taking a major release. A human should review the release notes and the preproduction test results prior to going live with any change what-so-ever, including patches.

@patricekrakow, unless you intend to issue a PR or have further questions or comments, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Nov 25, 2018): Then it might as well read _never bump the major version number_, because a breaking change for some is not a breaking change for all. A bump in the major version number literally translates into _"I publish this with the suspicion that it might break a sufficient number of my clients builds as to be harmful to my reputation, therefore I bumped the major version number"_. It does not translate into _"this release will break your build or application"_. Yes, the current wording is quite deliberate. You should never assume that any change is breaking/non-breaking in every use case, particularly yours. It makes sense to run automated updates to preproduction test environments, based on patch releases and, depending on the publisher, minor changes. A human should review release notes prior to taking a minor release, in most cases, and always prior to deciding on taking a major release. A human should review the release notes and the preproduction test results prior to going live with any change what-so-ever, including patches. @patricekrakow, unless you intend to issue a PR or have further questions or comments, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-04-20 10:01:06 -05:00

@sheldonh commented on GitHub (Jan 20, 2019):

Ask yourself why you would want to prevent me from arbitrarily bumping the MAJOR version number for reasons you haven't considered.

@sheldonh commented on GitHub (Jan 20, 2019): Ask yourself why you would want to prevent me from arbitrarily bumping the MAJOR version number for reasons you haven't considered.

GiteaMirror commented

2026-04-20 10:01:07 -05:00

@jwdonahue commented on GitHub (Aug 16, 2019):

@patricekrakow, unless you intend to issue a PR or you have further questions, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Aug 16, 2019): @patricekrakow, unless you intend to issue a PR or you have further questions, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-04-20 10:01:08 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

Thanks everyone for contributions, you're amazing 🎆 Did you find any consensus?

@alexandrtovmach commented on GitHub (Jun 10, 2020): Thanks everyone for contributions, you're amazing :fireworks: Did you find any consensus?

GiteaMirror commented

2026-04-20 10:01:09 -05:00

@patricekrakow commented on GitHub (Sep 25, 2020):

I think we all agree that the notions of incompatible/breaking changes and backwards compatible changes are relative. So even if the producer/provider thinks that the changes will be backwards compatibles for all her/his consumers, still some consumers applications can be broken. I really like the story in https://increment.com/apis/web-api-versioning/#defining-backward-compatibility and I am not questioning that.

What I am saying is that the semantics of a semantic version should be strictly limited to the belief of the producer/provider about the incompatible/breaking or backwards compatible nature of the changes she/he is proposing to her/his consumers, and not about any other considerations such as:

This change took me a long time to implement, it deserves an increment of the MAJOR;
It has been a while I am on the same major, the next change, whatever it is, I will increment the MAJOR;
We want to show off the great work we have done by incrementing the MAJOR;
...

@sheldonh you wrote: Ask yourself why you would want to prevent me from arbitrarily bumping the MAJOR version number for reasons you haven't considered. And my answer is that I would like to prevent you from abusing the semantics of semantic versioning. I hope it makes sense...

@jwdonahue I should now indeed create a PR. With or without "RFC" tag, that's the question...

@patricekrakow commented on GitHub (Sep 25, 2020): I think we all agree that the notions of _incompatible/breaking changes_ and _backwards compatible changes_ are relative. So even if the producer/provider thinks that the changes will be backwards compatibles for all her/his consumers, still some consumers applications can be broken. I really like the story in <https://increment.com/apis/web-api-versioning/#defining-backward-compatibility> and I am not questioning that. What I am saying is that the semantics of a semantic version should be strictly limited to the belief of the producer/provider about the incompatible/breaking or backwards compatible nature of the changes she/he is proposing to her/his consumers, and not about any other considerations such as: * This change took me a long time to implement, it deserves an increment of the MAJOR; * It has been a while I am on the same major, the next change, whatever it is, I will increment the MAJOR; * We want to show off the great work we have done by incrementing the MAJOR; * ... @sheldonh you wrote: _Ask yourself why you would want to prevent me from arbitrarily bumping the MAJOR version number for reasons you haven't considered._ And my answer is that I would like to prevent you from abusing the semantics of semantic versioning. I hope it makes sense... @jwdonahue I should now indeed create a PR. With or without "RFC" tag, that's the question...

GiteaMirror commented

2026-04-20 10:01:10 -05:00

@ljharb commented on GitHub (Sep 25, 2020):

@patricekrakow it is in no way abuse to bump the major even if there's no breaking changes.

@ljharb commented on GitHub (Sep 25, 2020): @patricekrakow it is in no way abuse to bump the major even if there's no breaking changes.

GiteaMirror commented

2026-04-20 10:01:10 -05:00

@rgwilton commented on GitHub (Feb 23, 2021):

Hi,

This discussion is interesting, and this topic (https://github.com/netmod-wg/yang-ver-dt/issues/78) has come up during the discussion of an IETF YANG versioning solution is based around Semver 2.0.0. https://www.ietf.org/archive/id/draft-ietf-netmod-yang-module-versioning-02.txt

Interestingly, my reading of the Semver spec seemed to match @patricekrakow's interpretation, but another IETF colleague has taken an interpretation closer to @jwdonahue. Specifically they would like the flexibility to bump the major version number when they release new major product versions, to give more flexibility to add backwards compatible enhancements to products that have been released and the software is being maintained.

But the key point is that different people are interpreting the Semver 2.0.0 spec in different ways, and that probably isn't helpful.

Hence, if the interpretation of Semver 2.0.0 is that flexibility is allowed, then it would arguably be helpful to clarify that in the Semver specification to remove the ambiguity.

Conversely, if it is not allowed, then it would also be helpful if the specification was strengthened to make that explicit.

Regards, Rob

@rgwilton commented on GitHub (Feb 23, 2021): Hi, This discussion is interesting, and this topic (https://github.com/netmod-wg/yang-ver-dt/issues/78) has come up during the discussion of an IETF YANG versioning solution is based around Semver 2.0.0. https://www.ietf.org/archive/id/draft-ietf-netmod-yang-module-versioning-02.txt Interestingly, my reading of the Semver spec seemed to match @patricekrakow's interpretation, but another IETF colleague has taken an interpretation closer to @jwdonahue. Specifically they would like the flexibility to bump the major version number when they release new major product versions, to give more flexibility to add backwards compatible enhancements to products that have been released and the software is being maintained. But the key point is that different people are interpreting the Semver 2.0.0 spec in different ways, and that probably isn't helpful. Hence, if the interpretation of Semver 2.0.0 is that flexibility is allowed, then it would arguably be helpful to clarify that in the Semver specification to remove the ambiguity. Conversely, if it is not allowed, then it would also be helpful if the specification was strengthened to make that explicit. Regards, Rob

GiteaMirror commented

2026-04-20 10:01:11 -05:00

@patricekrakow commented on GitHub (Feb 28, 2021):

See #619 for my final words.

@patricekrakow commented on GitHub (Feb 28, 2021): See #619 for my final words.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2082