mirror of
https://github.com/semver/semver.git
synced 2026-07-10 19:50:47 -05:00
[GH-ISSUE #1004] MAJOR should not be incremented unless backward incompatible changes exist #4864
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#4864
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @carlwiedemann on GitHub (Feb 2, 2024).
Original GitHub issue: https://github.com/semver/semver/issues/1004
This is a proposal likely not novel. In searching previous issues & PRs I didn't see anything about it.
I'd like to propose that a major increment shall not be made unless backward incompatible changes are introduced.
The language of specification item 8 would change. Something like this (bold text indicates something akin to what I propose):
8. Major version X (X.y.z | X > 0) MUST be incremented if any backward incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. It SHALL NOT be incremented unless backward incompatible changes are introduced to the public API. Patch and minor versions MUST be reset to 0 when major version is incremented.
I am hoping (perhaps in futility) this dissuades some of the capriciousness that I have seen with major increments. See https://github.com/mbleigh/acts-as-taggable-on/issues/1063#issuecomment-1924464963 for an example if you are keen.
Thoughts? Apologies in advance if this has been discussed & resolved in the past an I have simply missed it. Thanks!
@ljharb commented on GitHub (Feb 2, 2024):
Duplicate of #946.
There's nothing wrong with incrementing the major and having no breaks out of an abundance of caution - quite often a given user won't have any breakage even if the release does have breaking changes anyways.
@carlwiedemann commented on GitHub (Feb 2, 2024):
Thanks for linking the other issue, I appreciate it.
I generally agree with the opinion about "over-advertising" breakage vs "under-advertising" breakage.
That said, I'm still curious about what downsides making a change to item 8 would have. Perhaps I would instead propose using "should not" instead of "shall not" to acknowledge your comment that "it violates the spirit of semver, and is a gross and icky thing to do".
Perhaps I could put phrase it this way: In the world of FOSS, inappropriate versioning is going to happen de facto, whatever the specification decrees -- robust as it is, we'll still see (for lack of a better word) careless manintainers create breaking changes in minor & patch versions.
But conversely (for lack of a better word) careful maintainers may want to rely on a firmer specification than what exists today, to perhaps resolve debates whether a given change requires a major version bump. In my view, adding a "should not" (instead my previous suggestion of "shall not") could potentially help this debate move along, and avoid some of the "gross and icky" things we all have seen.
So I'd be interested to hear what risks & downsides would exist from making this change (using "should not"). That said, I do appreciate that we cannot know the full extent of the impact, and if that is grounds enough to avoid, then I am content with leaving this alone. And perhaps the "over-advertising" vs "under-advertising" should have precedence in the end. Fair enough.
Let me know what you think. I'm happy to close this out if you strongly believe this is settled and I am stirring the pot. Appreciate your time, at a minimum. 🙏
@ljharb commented on GitHub (Feb 2, 2024):
"should not" would be fine imo, but it wouldn't have any teeth, so i don't think it would help any arguments - which means i'm not sure what value there is in adding it.
@carlwiedemann commented on GitHub (Feb 3, 2024):
I see what you are getting at. I view its addition having some (perhaps marginal) value (which is why I went to the trouble of starting this discussion ;) ). So as it seems fine to you, I think I might open a PR for this.
Addendum (should it pique interest):
At the risk of bikeshedding (which I'd suspect is somewhat tolerated given maintainership of SemVer necessitates semantic navigation), I'm curious about your stated regard to the value of "should (not)" in general. More specifically: If you are "not sure what value there is in adding it," couldn't the same be said of any other location where "should (not)" is used?
As an example, consider item 4 -- presently, the only location where "should (not)" is used in the specification:
I'm curious, does this "should not" have value? If so, how is that value different than what I'm proposing?
As an exercise, we could compare its value to possible alternatives here, e.g. either (A) removing the third sentence from item 4 altogether, or (B) changing item 4 to use "shall not" -- finding lost "teeth" as you've described.
Are those alternatives of equal, lesser, or greater value? I suspect this may be a Rorschach test -- where one's reading of item 4 in its present form versus (A) as equal in value; while another's reading of item 4 in its present form versus (B) as equal in value.
So, without fully recapitulating the phylogeny of RFC 2119 I personally receive usage of "should (not)" to bears some (perhaps marginal) benefit, and I think this could be a good change if it can at least be tolerated by the maintainers.
I mention all of this as food for thought. I think for now I'll open up a PR and see how it fares -- if it happens to not gain appeal, that's fine. Again, I appreciate your thoughts & time here.
@ljharb commented on GitHub (Feb 3, 2024):
(to be clear, i'm not a semver spec maintainer)
Yes, that's a fair counterpoint about "shoulds".
@carlwiedemann commented on GitHub (Feb 3, 2024):
Ah, your alacrity suggested otherwise, very well. 😅 We'll see how the PR does.
@zafarkhaja commented on GitHub (Feb 3, 2024):
I agree with Carl, but I thought it was already kind of obvious from the spec.
There are three statements clearly telling us when to increment the major version, so we know when not to.
This list of one reason should be considered exhaustive as we can't rationally expect the spec to list all the non-reasons.
Also, pay attention to the third paragraph of the Introduction how it states that SemVer is all about a set of rules that dictate how version numbers are incremented and how the increments are meant to communicate changes to public API.
So I'd go as far as to argue that incrementing the major version without breaking changes goes against its semantics.
@carlwiedemann commented on GitHub (Feb 3, 2024):
Right, the sentence I'm proposing to add would maybe help with that problem. But I agree that specs aren't exhaustive and are subject to interpretation. I'm hoping this one additional sentence could help, but I accept it is only plausible at best.
@carlwiedemann commented on GitHub (Feb 3, 2024):
I should also mention that the comment that inspired this, from a OSS maintainer:
I think we'd agree that this is a misunderstanding of the specification. But the project in question is somewhat prominent, nearing 50M downloads. And, (though I am going out on a limb here) I believe that it is possible some maintainers who are not native English speakers may misunderstand some of these semantics, so some level of redundancy in the language may help here.
@ljharb commented on GitHub (Feb 3, 2024):
Sure - but why is that a particular problem? It just means that in order to update to it, you have to read the changelog to verify there's no breakage, and then you can update to it.
@carlwiedemann commented on GitHub (Feb 3, 2024):
I'll try to answer this through sharing some additional context.
For the particular project I have been working on, the Gemfile has nearly ~200 direct Ruby Gem dependencies, ~400 total including transitive dependencies. There are over 400k lines of tests. Upgrading the project from Ruby 2.6 to 3.0 took three full-time senior/staff engineers over 16 months of work, mostly due to complexities in dependencies.
Going through an effort like that has made me quite sensitive to accuracy of CHANGELOGs & adherence to SemVer in order to understand what version of a particular Gem is best to use for a given version of Ruby. Many CHANGELOGs are either inaccurate, or non-existent. It can be quite painful to have to do this at this sort of scale. Due to this experience, I suspect I am more sensitive to these things than others who have not gone though this.
For the particular example I mentioned earlier (with the act-as-taggable-on gem), I had to ask the maintainer directly whether the CHANGELOG was accurate, because it didn't list any breaking changes, so the major increments didn't make any sense to me. His reply was that "well major increments may contain non-breaking changes, so these major increments contain non-breaking changes"). Is he correct? I don't think he is. But he maintains a Gem with 50M downloads and I don't.
So I'd like to improve practices around these sorts of things, because I think it helps all projects, large & small. Adding a single sentence to the SemVer spec is one such effort. Is it adequate/exhaustive? I don't presume it to be. Many folks will see this as effective as yelling "stop" to a charging bear. But maybe it helps a few folks out there. I can't know, but I'm at least going to throw a few things against the wall.
That's the context here. I hope it helps.
@ljharb commented on GitHub (Feb 4, 2024):
Don't you have to do those verifications regardless? (which would usually be ideally covered by a thorough test suite)
Even in the JS ecosystem I wouldn't blindly trust the semver declarations of publishers in any direction, let alone in the Ruby ecosystem.
@carlwiedemann commented on GitHub (Feb 4, 2024):
It depends what you mean by "those verifications."
If you mean, "Don't you have to [read CHANGELOGS] regardless?" Yes, of course. I am not suggesting that any change to the SemVer spec is going to lead to a world where we can blindly trust SemVer -- that world will never exist.
If you mean, "Don't you have to [ask maintainers whether the CHANGELOG is accurate] regardless?" Mostly of the time, no. But I have done that when the CHANGELOG conflicts with the SemVer spec, namely the example I mention here where a major version is incremented despite having no breaking changes.
What I am suggesting is that by having tighter language in the SemVer spec may prevent discrepancies where maintainers are capaciously incrementing major versions despite having no breaking changes. And it would enable me to point to the spec to (hopefully politely) suggest to a maintainer that they might use more caution in the future when picking a version number.
Both you and I understand that
"major" === "breaking"but sadly I think others think"major" === "significant whether breaking or not". I'd like to move people from the latter camp to the former camp by having tighter language in the SemVer spec because I think (perhaps naively) it will lead to better CHANGELOGs.@ljharb commented on GitHub (Feb 4, 2024):
I meant, run your tests and ensure your program works as expected. Asking the maintainers shouldn’t be needed unless your tests aren’t sufficient.
@carlwiedemann commented on GitHub (Feb 4, 2024):
You are talking about the ideal, de jure, while I am talking about the actual, de facto.
The codebase I am working on is one that has been contributed to by hundreds of engineers at my company over 10 years, with dubious contributor history. Many changes were made without following strict TDD, and predated my own involvement by several years. Can you relate?
I have shown you an example of where a prominent OSS project misunderstands SemVer. I am proposing a change to the spec that I think would help this misunderstanding. I have witnessed these misunderstandings compound when working at a large scale of upgrades and add work to understand whether a CHANGELOG is accurate, which cannot be asserted easily in a dubious test suite, which I believe is (unfortunately) common in many large organizations, such as my own. If I could snap my fingers and change the past, I would.
If you have experienced otherwise, where tests are especially clairvoyant, you might consider that your own experience is not universally enjoyed, and that you may be making an argument from incredulity.
But presumably you do care about having a good spec, and believe that the spec matters. (Why would you participate in this issue queue otherwise?) So I must say that I don’t understand your aim at this point. Can you clarify your concerns you have with my proposed change a bit more? Because right now it appears to me you are simply looking to debate for sport and litigate the merit of my experiences. I don’t find that productive, and I doubt our progeny reading this thread in the future will either.
If you think my proposed change to the spec makes the spec worse, then let’s discuss why. I don’t think it does. Do you? Why? What are the risks? Let’s hear them. I am quite open to material feedback here, and even closing this issue and the PR — albeit I would prefer to hear more opinions, especially those of the maintainers themselves.
If I am misunderstanding you, then I apologize. Sorry. But may I suggest you write a bit more in your next reply so that I may empathize better? I currently am having difficulty. Thanks.
@ljharb commented on GitHub (Feb 4, 2024):
Any additions increases complexity, which is inherently harmful - so the benefit to additions would need to be greater than that harm. I'm not personally convinced there's any benefit to be had here.
To be sure, there's no harm specific to the suggested changes :-)
@zafarkhaja commented on GitHub (Feb 4, 2024):
@carlwiedemann
I was actually saying that we should treat specifications as exhaustive. I believe, specifications are supposed to be specific, with as little room for interpretation as possible. That's why if something isn't clear, it should be clarified.
@zafarkhaja commented on GitHub (Feb 4, 2024):
@ljharb
For one, it complicates dependency management automation, which has become easier thanks to SemVer's universal rules. Unless you have AI-powered tools, reading tens or hundreds of changelogs (if even present) may be tedious.
@zafarkhaja commented on GitHub (Feb 4, 2024):
@ljharb
Agree, but only because I already think the spec is clear about this. But if it's just me and it's not, we should at least clarify.
@carlwiedemann commented on GitHub (Feb 4, 2024):
@zafarkhaja @ljharb
The benefit that I believe is this:
Right now, item 8 can potentially be interpreted as is being done in this comment by a maintainer of a project with nearly 50M downloads.
I believe this maintainer is reading item 8 to mean that a major version bump is allowed without breaking changes, but simply if the maintainer believes that the changes are "significant." In other words, if we take the first two sentences of item 8 as sentence
Aand sentenceB, then the misinterpretation I believe is in reading that a major increment is allowed whenA || Binstead of whenA && B.That interpretation may be wrong but it is happening, and in prominent projects, as I have demonstrated.
I believe the spec itself bears some responsibility for its own (mis)interpretation. If it is not clear, then I think it should be clarified. Clarification may require addition. Whether the spec is clear to you or me is less important than what we observe happening at large. What I observe is prominent OSS projects misinterpreting the spec. So I am not deferring to my personal interpretation of the spec, because I believe I understand its core intent, I am instead deferring to my observation what I see happening in the world.
So while you may argue "any addition increases complexity," I would respond by saying that complexity can also arise from a lack of clarity.
@ljharb commented on GitHub (Feb 4, 2024):
It is 100% allowed, and would continue to be with this change, to publish a major bump without breaking changes. There’s gobs of reasons that ability is critical to preserve.
@carlwiedemann commented on GitHub (Feb 4, 2024):
I’d love some examples of these reasons. Can you describe some?
@ljharb commented on GitHub (Feb 4, 2024):
I don’t have to be certain there’s breaking changes to be concerned there might be some - bumping the major out of an abundance of caution is wise, because the cost of a break in a non-major (automated systems and production systems failing) is much, much bigger than the cost of a major without a break (which happens all the time, since most breaking changes don’t affect every user).
@carlwiedemann commented on GitHub (Feb 4, 2024):
@ljharb
You didn’t answer my question. You claim there are “gobs” of reasons that do not pertain to breaking changes. I asked you to name some examples. Can you?
Instead you described a situation that is also related to breaking changes — the “abundance of caution” would be for the possibility of a breaking change. That is not what I am referring to, I am referring to when there is knowingly no breaking changes, yet the major is incremented anyway. You claim there are gobs reasons for this. Please name them.
@ljharb commented on GitHub (Feb 4, 2024):
That wasn’t my claim; the “possibility” of breaking changes IS “no breaking changes”, as far as I’m aware at the time. In other words, i don’t think there’s any way to stop the behavior you dislike without compromising the ability to be cautious.
@carlwiedemann commented on GitHub (Feb 4, 2024):
@ljharb
I have said before I don’t presume my proposed change to be a panacea. It is a “should” not a “shall.” I am hoping it helps clarify, that is all. I have made no claims to “stop” anything, those are your words, not mine.
The example of being “cautious” is not what I am describing. I am not opposed to caution, and I would hope that maintainers mention such reasoning in their CHANGELOGs.
But you still haven’t named any other examples, despite your claim of being “gobs” and me asking twice. It seems to me you are intent to simply argue with quippy, brief replies. I don’t find it productive.
@ljharb commented on GitHub (Feb 4, 2024):
Yes, i keep my replies brief because essay comments are what’s unproductive.
Another reason is because the conceptual intention of the package may have changed, without changing the API or behavior. For example, the officially supported use cases.
@carlwiedemann commented on GitHub (Feb 4, 2024):
I am telling you I don’t find your replies productive. Do you understand?
Please point to an example project where this was the case. Please also name more examples from your “gobs”. I am asking you for details and actual examples from actual projects.
@ljharb commented on GitHub (Feb 4, 2024):
Yes - I told you the same, do you understand?
It seems this isn't useful to keep discussing. I don't think your change should land, and I think the maintainer you reference hasn't done anything wrong. Perhaps a semver maintainer will disagree.
@zafarkhaja commented on GitHub (Feb 4, 2024):
@carlwiedemann
Personally in this case I don't think adding "should" is a step in the right direction. As it is, the spec already doesn't "allow" incrementing the major version without breaking changes to public API. Allowing it would be a step backwards.
As was previously said on many other different occasions, SemVer shouldn't try to please everyone or cover all possible cases out there. It proposes a solution to a very specific problem, "dependency hell", which is explained in the Introduction section. You either adopt it, or you don't. There are many tools and libraries that have the same version scheme but they are not fully compliant with SemVer in one way or another, nor do the claim to be. But someone's claiming to follow SemVer doesn't mean there won't be any accidental violations. Some of those hypothetical exceptional situations are already covered in the FAQ section.
SemVer is a contract between suppliers and consumers which can't be programmatically enforced (yet?). So, at the end of the day, it's a matter of trust.
@akostadinov commented on GitHub (Feb 5, 2024):
Such change would not be productive. Besides allowing project owners to freely choose what constitutes a major change, a very practical reason NOT to introduce such a restriction can be something like this.
For example a subsystem of a project is rewritten for whatever reason. The tests show it compatible for every use case that the developers could think of. But this is still a major change and before the project is thoroughly battle tested in practice, one can't be sure that the behavior didn't really change in edge cases or that there are no bugs introduced.
So it would be a service to the users to know that nothing major changed if they stay on version 9 for example. And they would upgrade to 10 with more caution and testing despite not having to change the way they use the project.
@carlwiedemann commented on GitHub (Feb 5, 2024):
@akostadinov This is exactly the problem: That the definition of "major" is understood loosely. Generally speaking, I believe the spirit of SemVer equates
major.minor.patchtobreaking.feature.fix. The problem with the word "major" is that it has many different meanings in English. But in the parlance of SemVer, I believe it should (not shall) mean "breaking." It is the particular parlance that concerns me. And I am intending to use "should" rather than "shall" to provide for certain edge case allowances. That is my proposal.This is true of every change made to any software, whether it is rewritten or not. To paraphrase Dijkstra, testing only shows the presence of bugs, never the absence of bugs.
As I mentioned in a previous comment I believe my proposal affords for an abundance of caution. And, these cautious maintainers we speak of would surely be cautious enough to write a rigorous reason in the CHANGELOG why they are electing to choose a major increment. I have no problem with that, because it is not capricious. I am looking to reduce capricious increments by including a "should" in the spec.
@zafarkhaja commented on GitHub (Feb 6, 2024):
@carlwiedemann
I agree, and this is why I don't think your proposal is addressing the real problem. It's one thing to clarify things, and it's another to change their semantics to make up for "inaccurate" naming.
Moreover, keep in mind that
minorandpatchare also not without a flaw. So, to be consistent we would need to apply a similar change to them too. Which, in my opinion, would effectively nullify the whole purpose of SemVer.@carlwiedemann commented on GitHub (Feb 11, 2024):
@zafarkhaja
I guess I'm deferring to incremental improvement here. This is a proposal of an evolution, not a revolution.
I'm trying to clarify at this phase.
You are correct. But that's not the aim here. The aim here is to improve "major". I think working toward small goals can be useful, because otherwise we end up recapitulating the entire spec, as you have identified correctly.
So I don't see how your statements preclude the value of improving item 8 in the spec, as I have illustrated. Surely we can make small improvements in certain areas without addressing the entire document, no?
@zafarkhaja commented on GitHub (Feb 11, 2024):
@carlwiedemann
I'm totally for small goals and incremental improvements, it's just that in this case I fail to see how it's an improvement.
If we carefully read the Introduction section,
it basically says that the whole purpose of incrementing a version number is to communicate changes to public API.
Your proposal, on the other hand,
makes it possible to increment the major version without a breaking change. So how will we know then what's being communicated? Will we have to read tens or hundreds of release notes, if even available?
@carlwiedemann commented on GitHub (Feb 11, 2024):
How does my sentence make it possible? Is it because I am using “should” instead of “shall”?
Secondly, do you believe that the spec already does not make it possible? Because many people seem to disagree with that.
@zafarkhaja commented on GitHub (Feb 11, 2024):
Yes, because of "should not" (as defined by RFC 2119). Without an explicitly specified finite list of "valid" reasons, it will essentially be used as a loophole. In any case, it would defeat the purpose of the major version number. "shall not", as you initially proposed in your first post, was a better word choice.
Yes, I believe so, and that's what I was trying to convey all along. And apparently failed at that.
True, but let's not give them a legal ground as well :) Seriously though, they may disagree, but I would expect them to be able to support their claim by referring to the specification.
@carlwiedemann commented on GitHub (Feb 12, 2024):
@zafarkhaja
I think that is a great observation. I was sort of “soft-pedaling” here to be a bit gentler, but I can see how it would backfire.
I guess at this point I want to think about this some more. Basically my concerns are that I don’t think SemVer as-is has been strong enough in its definitions. Some people see that as a feature, other people (like me) see that as a bug.
But to your point, revisiting some of these things really recapitulates the entire spec. So the strictness that I’m looking for probably would amount to “SemVer 3.0.0”.
I’m wondering what the appetite for that is among people who have maintained SemVer? I’m a newcomer to this project, but I would suspect some flexibility in the definitions is valued more than I might value it.
I might be interested in proposing something different altogether here. I’m going to chew on it.
Thanks @zafarkhaja for your input, it has been useful.
@zafarkhaja commented on GitHub (Feb 12, 2024):
@carlwiedemann sure, don't mention it 👍
Only if you break something, clarifications don't count as breaking.
@carlwiedemann commented on GitHub (Feb 12, 2024):
@zafarkhaja
Right, I guess I am anticipating whether changes that add “shall” would be viewed as breaking or not (based on earlier comments made in this issue and in https://github.com/semver/semver/issues/946). I see there is a lot of inertia for various meanings of “major.”
I think I will take a crack at drafting a separate spec from scratch and see what it looks like, even if it is just for recreation. I’ll drop a link to it when I have something as I’d be interested to hear your take. 🙂
@zafarkhaja commented on GitHub (Feb 12, 2024):
@carlwiedemann
Interesting, as I had a similar idea after you started this thread :)
As for that thread you mention, as usually is the case whenever there is a debate, we don't back up our claims with the specification itself, we rather tend to rely on our subjective understanding of it. And that's one of the problems of SemVer, in my opinion, as it leaves room for interpretation of its core concepts.
@steveklabnik commented on GitHub (Feb 14, 2024):
have had lots of discussions about cleaning up various parts of the spec. the idea would be to make it transparent to actual implementations, that is, not make major changes, as those realistically are not going to be adopted. but haven't had the time/will/energy.
@Lxstr commented on GitHub (Feb 16, 2024):
Here's a current situation I'd like to understand. There's a package that needs one of its dependencies replaced by another drop in replacement (but incompatible elements) dependency. Minor version would used both to erase the transition. Any interacting user would be switched over to the new format seamlessly. However, once the the old one is removed, any users that haven't been interacting in that time period will be logged out. This is one of the core aspects of the package changing, security improving, users may be interrupted but technically no API is broken. What versions should be used?
@ljharb commented on GitHub (Feb 16, 2024):
@Lxstr this really belongs in its own issue, but “being logged in” seems like a pretty important part of the API to me.
@Lxstr commented on GitHub (Feb 16, 2024):
Sure I can start a separate issue if that's better but I guess this was intended in the context of this issue to highlight how it's not always clear to someone what specifically Broken API actually means and for someone new or perhaps with a literal interpretation to understand. My first thought was that it's technically not the API as no deployments will complain or crash. If programmers may not even notice, surely it's not breaking the Programming Interface. But my common sense would kick in and say they would probably still care quite a bit. I would tend to choose a major version for the replacement but only because I am allowed the leeway of SHOULD.
Unless I am missing something and it should be a minor version, I guess I am pointing out that it might be better to explain that leeway must not be abused for things that do not constitute major upheaval. For example the marketing case or the example used here regarding the gem.