Why Semantic Versioning Isn't

semantic-pedantic.md

Spurred by recent events (https://news.ycombinator.com/item?id=8244700), this is a quick set of jotted-down thoughts about the state of "Semantic" Versioning, and why we should be fighting the good fight against it.

For a long time in the history of software, version numbers indicated the relative progress and change in a given piece of software. A major release (1.x.x) was major, a minor release (x.1.x) was minor, and a patch release was just a small patch. You could evaluate a given piece of software by name + version, and get a feeling for how far away version 2.0.1 was from version 2.8.0.

But Semantic Versioning (henceforth, SemVer), as specified at http://semver.org/, changes this to prioritize a mechanistic understanding of a codebase over a human one. Any "breaking" change to the software must be accompanied with a new major version number. It's alright for robots, but bad for us.

SemVer tries to compress a huge amount of information — the nature of the change, the percentage of users that will be affected by the change, the severity of the change (Is it easy to fix my code? Or do I have to rewrite everything?) — into a single number. And unsurprisingly, it's impossible for that single number to contain enough meaningful information.

If your package has a minor change in behavior that will "break" for 1% of your users, is that a breaking change? Does that change if the number of affected users is 10%? or 20? How about if instead, it's only a small number of users that will have to change their code, but the change for them will be difficult? — a common event with deprecated unpopular features. Semantic versioning treats all of these scenarios in the same way, even though in a perfect world the consumers of your codebase should be reacting to them in quite different ways.

Breaking changes are no fun, and we should strive to avoid them when possible. To the extent that SemVer encourages us to avoid changing our public API, it's all for the better. But to the extent that SemVer encourages us to pretend like minor changes in behavior aren't happening all the time; and that it's safe to blindly update packages — it needs to be re-evaluated.

Some pieces of software are like icebergs: a small surface area that's visible, and a mountain of private code hidden beneath. For those types of packages, something like SemVer can be helpful. But much of the code on the web, and in repositories like npm, isn't code like that at all — there's a lot of surface area, and minor changes happen frequently.

Ultimately, SemVer is a false promise that appeals to many developers — the promise of pain-free, don't-have-to-think-about-it, updates to dependencies. But it simply isn't true. Node doesn't follow SemVer, Rails doesn't do it, Python doesn't do it, Ruby doesn't do it, jQuery doesn't (really) do it, even npm doesn't follow SemVer. There's a distinction that can be drawn here between large packages and tiny ones — but that only goes to show how inappropriate it is for a single number to "define" the compatibility of any large body of code. If you've ever had trouble reconciling your npm dependencies, then you know that it's a false promise. If you've ever depended on a package that attempted to do SemVer, you've missed out on getting updates that probably would have been lovely to get, because of a minor change in behavior that almost certainly wouldn't have affected you.

If at this point you're hopping on one foot and saying — wait a minute, Node is 0.x.x — SemVer allows pre-1.0 packages to change anything at any time! You're right! And you're also missing the forest for the trees! Keeping a system that's in heavy production use at pre-1.0 levels for many years is effectively the same thing as not using SemVer in the first place.

The responsible way to upgrade isn't to blindly pull in dependencies and assume that all is well just because a version number says so — the responsible way is to set aside five or ten minutes, every once in a while, to go through and update your dependencies, and make any minor changes that need to be made at that time. If an important security fix happens in a version that also contains a breaking change for your app — you still need to adjust your app to get the fix, right?

SemVer is woefully inadequate as a scheme that determines compatibility between two pieces of code — even a textual changelog is better. Perhaps a better automated compatibility scheme is possible. One based on matching type signatures against a public API, or comparing the runs of a project's public test suite — imagine a package manager that ran the test suite of the version you're currently using against the code of the version you'd like to upgrade to, and told you exactly what wasn't going to work. But SemVer isn't that. SemVer is pretty close to the most reductive compatibility check you would be able to dream up if you tried.

If you pretend like SemVer is going to save you from ever having to deal with a breaking change — you're going to be disappointed. It's better to keep version numbers that reflect the real state and progress of a project, use descriptive changelogs to mark and annotate changes in behavior as they occur, avoid creating breaking changes in the first place whenever possible, and responsibly update your dependencies instead of blindly doing so.

Basically, Romantic Versioning, not Semantic Versioning.

All that said, okay, okay, fine — Underscore 1.7.0 can be Underscore 2.0.0. Uncle.

(typed in haste, excuse any grammar-os, will correct later)

I see SamVer at least bringing some layered context to versioning: the versioned backwards compatibility against a public API. With the rants out of the way, what's considered better than SamVer by 2020 standards?

Nailed it. I see a lot of these "SemVer is terrible" rants and for the most part find myself agreeing with them, but then they either neglect to discuss alternatives at all, or pretend that those alternatives are somehow immune from those very same issues that they lambast SemVer for.

To misquote Winston Churchill "SemVer is the worst form of version identification, except for all those other forms that have been tried from time to time". I'm open to the possibility that a better scheme exists, but have yet to see anyone describe such a thing in detail.

Bad take.

A common misunderstanding is that semantic versioning is meant to be used for software version numbers. It's not.

Semantic versioning is used for packages / libraries that have a public API that is consumed by other software (and used by their respective developers). And it was never intended to do anything else.

Only in the context of an API, SemVer has any meaning at all:

• Bugfix version increase -> It fixes bugs. It does not add features. It does not break backwards compatibility in any way.
• Minor version increase -> It might fix bugs. It does add new features or extend existing features (and the corresponding API), but still allows it to be used in the same way as before (but without the new functionality). It might deprecate functionality without actually removing it.
• Major version bump -> It might fix bugs and/or add new features. Whatever it does, it breaks backwards compatibility with the last version in at least one aspect of the public API.

For everything besides APIs, either use romantic versioning, marketing version numbers, code names, or whatever you see fit. If you have a software product that offers an API to connect other systems to it next to a UI that is consumed by actual users, you might just as well use a marketing version number for your software, while using SemVer to version the API - I've actually seen quite a few products do just that.

IMHO:
Changing an API in an backwards incompatible way is something completely different to breaking someones code that has this dependency.
One can occur without the other and this relates to both.
Semantic Versioning does only state, when an backwards incompatible change is present and when there is a new feature, nothing else.

From my point of view, the author is mixing (planned/intended/documented) API changes and actual implementation changes.
I consider this something completely different.

I also do not see the point, regarding the resoning, that some projects do not use SemVer.
If a project in question does not use SemVer, than you do not interpret its versioning as SemVer.
To expect that a project's versioning represents SemVer, if it is not stated or when it is actively not complied to,
does not make any sense to me.

Rich Hickey, the creator of Clojure, talked about this in his spec-ulation presentation, which was created two years after this gist. He talks about similar issues with semantic versioning and the general way we convey change, stating that we should value accretion over breaking changes and properly manage location for when deprecation is necessary (from variables up to namespaces/modules).

I think it's an excellent talk that conveys the issues with semantic versioning in better detail and an alternative to it.

@kyleerhabor as a Clojure developer myself, I reluctantly find myself scratching my head a bit with Rich Hickey's views in this area (despite also encouraging everyone to check out his presentations).

Yes it is self-evident that we should all aspire to only accrete, relax, and fix our libraries (and a majority of the time that's indeed entirely reasonable), but in my experience, in any non-trivial, long-lived codebase there almost always comes a time where something has to change in a way that will break consumers, and can't simply live on in perpetuity as a deprecated, but still functional, feature. Typically this is ultimately because something in the real world changed in a backwards incompatible way; a standard, a human process, a third party system, a business priority, legislation, etc. etc. ad nauseam.

Semantic versioning at least gives us a standardised way to identify different classes of change (even if it's far from perfect).

@pmonks thanks for the response. Rich Hickey's presentation is one of his most controversial, some of it I even find confusing. Often, the real world and other dependants get in the way of the "accretion without breakage" philosophy. Rich doesn't talk about it in his presentation, but he does mention other examples with solutions.

For example, if your software is not used by a third party (e.g. a client hitting the endpoint), you don't have to apply any of Rich's principles since you're free to modify in a fixed environment. However, if it is, it depends on how it's used. Are you running a public web server, or providing a public library? You can still apply the principles in both environments, but there are some cases where deletion is the only option (last case scenario).

Software should be designed to support these changes by not coupling too tightly. If you hit POST /articles with a new article and a new field is required, a new endpoint POST /articles2 could be created while sharing logic in the presentation layer (GET articles/...). However, if an external force prohibits you from maintaining your stack, deprecation arrives. In serious cases, deletion arrives (e.g. you were storing something but now you can't). In a library, when a breaking change is necessary, deprecation or even a new namespace can be a solution. When the whole library needs to be refactored, a new library may satisfy.

In Datomic, for example, you have excision, which is only used when you absolutely have to delete data (e.g. the GDPR's "right to be forgotten"). But often, these measures are inefficient. Not only for performance, but in actual deletion of the data. If you delete the data but have a backup, you've failed to acknowledge the user's request to delete the data. One solution is crypto-shredding where the data is encrypted and the decryption key is deleted so the data is locked forever.

Semantic versioning is popular since it models the real world but the cost to consumers can be very detrimental. In my opinion, like the author, it's not a great way to identify classes of change. Like Rich said, with patch and minor, you don't care. With a major change, you're screwed. What do versions 1.5.0 and 2.0.0 convey? Is it a small change or a complete overhaul? Will it take Sam 10 seconds to fix and Bob a week? Changelogs are answers to that, but the version itself doesn't say much. Accretion over breakage is not immune to the real world but is one solution to the problem. It does work in many applications but has mixed feelings. HTML, Unix, and Java to name a few. It requires a lot of discipline.

Thanks @kyleerhabor - I assure you I have a solid understanding of the concepts. The reality is that unavoidable breaking changes, however rare, do happen, and the only practical solution I know of in such cases is to communicate those breaking changes as clearly as possible, and ideally with as much lead time to downstream consumers as possible.

Which gets us back to my original point: while it is clearly far from perfect, SemVer at least provides a standardised, machine-consumable, ordered (both in the sense of "sorting", and in the sense of "disciplined") way to communicate breaking changes. Simply coming up with a new name for something that's broken backwards compatibility doesn't even have those benefits; it's a "wild west" / "do whatever you want" solution that ignores the needs of downstream consumers.

@pmonks thanks - I only watched the talk recently, so there are certainly people who have a much better understanding than me. Unavoidable breaking changes can happen, but it depends on what the project is. If a project depends on a service that prefers breaking changes (let's say an API), then sure—accretion over breakage is not sustainable. However, many projects can use it instead of semantic versioning.

Underscore is, in my opinion, a perfect example of where accretion without breakage would've worked. Instead of changing an existing function, it could've been marked as deprecated and suggest users use a newer function with a different definition. It would've been feasible since it's a utility library for writing functional JavaScript.

But not all libraries get such luxury. A library that chooses accretion without breakage relying on another library that instead uses semantic versioning is a bit difficult. Semantic versioning dominates the game in many ecosystems. Node.js follows it (except with odd numbers) and so does npm, making it the de facto choice.

But not all ecosystems are like that. In Clojure, it's a mix between unclear versioning semantics and accretion without breakage. It's machine-consumable, ordered (many libraries include the number of commits in a component), and just requires not deleting or changing the meaning of a function. In Rust, although it uses semantic versioning, the compiler strives to be completely backward compatible and introduces minor hacks to get around accidental breaking changes. A program I wrote in 2016 Rust will compile in 2021 and gets around it by introducing editions to make breaking changes.

So, yes, I do agree that accretion without breakage is difficult for some projects today. I don't think it's a one-size-fits-all like semantic versioning is. However, it's an alternative to semantic versioning. It means upgrading a library version without worrying about the breaking changes it could've introduced because there are none. It means minimizing backward-incompatible changes and being explicit about what necessary changes were made (did 2.0.0 change one function or 100 of them?). It's not just about libraries and applications—it's about producers, too. APIs are capable of applying their principles as well. Incompatible changes will happen since we live in a stateful universe, but like how Clojure offers features to properly manage the transition between states, we're offered an alternative to semantic versioning and responding to breaking changes.

@pmonks, sometimes renaming a library is IMHO the only reasonable way - look for example at the story of Apache Commons Lang 3. I think that this is what @kyleerhabor meant when writing about introducing a "new namespace".

@pbodnar sure, though their solution is driven more by Java's lack of version-aware modularity than anything wrong with SemVer. In fact it's interesting to observe that not only did the authors of Apache Commons roll the version number in accordance with SemVer, their workaround to the problem I mentioned in the previous sentence involved duplicating the new major version number into the Java package names. One might argue that they doubled down on SemVer.

If your package has a minor change in behavior that will "break" for 1% of your users, is that a breaking change?

Yes. I do not understand how the % is important. It is a break for some users and the release notes will describe who are impacted. As you bring up the issue of severity of breaking change, % impacted etc, then the version bump highlights that there is a breaking change drawing closer attention to the release notes. I treat a path bump very different to a major bump.

You could evaluate a given piece of software by name + version, and get a feeling for how far away version 2.0.1 was from version 2.8.0.

I wonder if this is merging product versioning and software artifact release versioning. I see them as very different and I use SemVer for software artifact versioning for what the software team deems to be a release which is a different to product management releasing a product. Yea but that is all about context isn't it.

Software package releases should post their the package-specific version (i.e. Romantic Version or Calendar Version) as well as a mandatory semantic version. The package version would just be X.Y.Z, etc. while the sematic version identifier would be be prefixed with semver- like semver-<semver-id>. So Package X would have the semver version identifier semver-2.3.1, semver-4.1.0-rc.5, etc. where the sematic version number is 2.3.1, 4.1.0-rc.5, etc. That way, the package could advertise the package-specific version (i.e. Romantic Version or Calendar Version) but package managers and other fastidious actors would query and pull based on the semantic version number.

There would be some conventions needed so that packages would publish both the project-specific version and their sematic version. And if you pulled the semantic version semver-2.3.1 it would be nice to find out its project-specific version 1.5.1 and visa versa.

It is common for software project release to have multiple version identification schemes.

Problem solved. Everyone can have their cake and eat it too. Next cliche ...

Software package releases should post their the package-specific version (i.e. Romantic Version or Calendar Version) as well as a mandatory semantic version.

Nice thinking. Very interesting. But I do not quite see it :-)

You say "package-specific version" and "mandatory semantic version". Who is the user for each? The work mandatory is interesting, it implies a second player.

If I guess that "package specific version" is a product version like "Visual Studio 2022" then would that not be the name and not the version? For example:

My product_2024.8.1_1.2.3-rc.5.ext

Even that would seem odd to me as it is not clear why I would want to have 2 versions in the one name. If the end user expects "2024.8.1" why add a semver? But that comes back to the "mandatory" word.

@RobSmyth the user for the semantic version is the package manager. When a person tells the package manager to upgrade a package, the package manager compares semantic versions to determine what it can safely upgrade to.

The romantic number would be purely to satisfy humans who want a subjective number, and provides no objectively useful information.

This has been the problem with getting people on board with semantic versioning - people are used to thinking version numbers are for humans. But version numbers should be for machines - only then are they objectively useful.

Being able to signal a substantially significant upgrade is objectively useless?

Yeah people keep repeating this false notion that any information outside of the regular Breaking.Feature.Patch is "purely to satisfy humans' subjective desires". Wrong. There is a big practical difference between a "small breaking change" (eg. changing a single parameter of a single function) versus a "library overhaul" (eg. changing >50% of the functions and structures in a library). If it's a "small breaking change" (see above), then a dev with an hour left at work can update the dependency and expect to adjust the codebase in time. If it's a "library overhaul" (see above), then they would not expect to be able to. The distinction being there in the version number itself (as opposed to having to check the changelogs *every time*), is thus of *practical benefit*, ie. it is not purely to satisfy humans' subjective desires. (And yes, *current tooling* would treat large and small breaking changes the same way. But this could also be changed, eg. tell npm to update all packages, but only extending to "small breaking changes", not library overhauls. Again, this has *practical utility*, for some people's workflows.) That people keep repeating the false notion of a fourth number being "of no use practically" is a sign of either bad faith arguing, or lack of familiarity with the reasons many people find the current Semantic Versioning insufficient.

So if a package indicates a breaking change is minor you would want to automatically upgrade to it and just see if it works without reading the changelog to make sure the breaking change doesn’t affect you? Or is it that you would always read the changelog when you do a baking upgrade, but you want to decide if you should even bother before looking up the changelog?

I wouldn’t personally want to risk a “minor breaking upgrades across the board” operation. But I wouldn’t be opposed to letting other people do that I guess. The main thing that’s a problem is people wanting to sweep minor breaking changes under the rug, in which case no automatic upgrade of any kind is wise.

So if a package indicates a breaking change is minor you would want to automatically upgrade to it and just see if it works without reading the changelog to make sure the breaking change doesn’t affect you?

Not as an every day operation, but in some cases yes; for example, if there's a project I haven't worked on in some months, I will sometimes want to get the dependencies more up-to-date, but not have to deal with a 6+ hour refactoring headache (ie. avoid major library revamps). In those cases, triggering automatic upgrades that permit only "small breaking changes" would be useful to me.

The main thing that’s a problem is people wanting to sweep minor breaking changes under the rug, in which case no automatic upgrade of any kind is wise.

Yeah that can be a problem. I think having four digits (MajorBreaking.MinorBreaking.NonBreaking.Patch) would reduce the occurrence of this problem though, because library devs can then increment the version digit accurately (MinorBreaking), while communicating the intent that "yes this is technically breaking but any corrections will be fast or even unnecessary,".

The end developer can then choose whether they want to opt into that "small but breaking change", or avoid any breaking changes whatsoever.

Would a change like dropping support for Node version X be major, or super major?

It wouldn’t entail any refactoring, but then again, it might be a complete dealbreaker for projects that are stuck deploying to older versions of node for the time being.

And it would be the kind of thing where if you get that breaking upgrade automatically, and aren’t careful what version of Node you’re using locally, everything could seem fine for awhile, theoretically it could even get released if none of your testcases happen to trigger the codepath that uses new syntax or APIs etc.

If you want to skip reading the changelogs for personal project deps, there’s no problem with taking that risk alone. But if anyone else uses your code, they could get burned if you don’t check changelog entries for breaking changes, no matter how minor.

@lolmaus being able to indicate whether there were breaking changes is objectively useful, it enables you to automatically upgrade all of your deps to the newest minor version, and as long as package maintainers are cooperating with the versioning scheme (most major OSS projects do), you can rest assured you didn’t get any breaking changes. It’s “objective” in the sense that code can make a reasonable decision based upon it. Automated decision making from subjective information doesn’t work as well, or at the very least is much more complicated (e.g. AI)

i don’t think that signaling small vs large breaking changes is objectively useful for code making decisions though. I don’t see how an automated process could provide any guarantees off of some number that indicates the “degree” of breaking changes.

Would a change like dropping support for Node version X be major, or super major?

I would consider that MajorBreaking (rather than MinorBreaking), because of scenarios like you mention, where a deploy environment has versioning constraints (or, eg. another library only has native binaries for certain NodeJS versions); but yes, subjectivity exists there.

Like many things in life though, a distinction can be on average beneficial to signal, even if there is not an objective/unambiguous cutoff for it.

And it would be the kind of thing where if you get that breaking upgrade automatically, and aren’t careful what version of Node you’re using locally, everything could seem fine for awhile, theoretically it could even get released if none of your testcases happen to trigger the codepath that uses new syntax or APIs etc.

Yes, that is an example of a case where using automatic upgrade of the "MinorBreaking" could cause unintended problems.

But two points:

• If the project is critical, and you don't have extensive test cases, you don't have to do upgrades of "MinorBreaking"; you can keep using the existing SemVer behavior and avoid both "major" and "minor" breaking changes. It's opt-in, so devs can weight the pros/cons per project. (ie. I do not advocate for the default being auto-update of minor-breaking changes)
• Even apart from auto-update commands, I think a fourth digit is useful independently, because it signals information to the end developer (in a compact, globally visible way) whether the library developer is declaring the change as likely to require substantial changes to update to or not. (eg. letting end developers selectively inspect the changelogs of updated libraries)

In short: I think the utility gained from that extra digit outweighs the costs. If you disagree on that weighting, that's fine; but I wanted to explain the reasons I'd find it useful, in practical terms -- and that it is not sought simply because it "looks more appealing" or the like.

@lolmaus being able to indicate whether there were breaking changes is objectively useful, it enables you to automatically upgrade all of your deps to the newest minor version, and as long as package maintainers are cooperating with the versioning scheme (most major OSS projects do), you can rest assured you didn’t get any breaking changes. It’s “objective” in the sense that code can make a reasonable decision based upon it. Automated decision making from subjective information doesn’t work as well, or at the very least is much more complicated (e.g. AI)

You are making a lot of mistakes here:

1. I didn't ask whether the major version number is objectively useful or not. I don't question its usefulness. My question was about the higher-level version number. I like to call it "generation".
2. I didn't ask whether something is objective or not. I asked if something is useful.
3. I didn't ask about automated decision making at all. Semver is more or less fine in this regard. This thread is about human convenience and reasonable meaningfulness, not about automation.

TL/DR: stop trying to win this argument on the automation field of battle. We're not following you to that field, you can go fight there alone or with your automation friends. We will stay here on the human convenience field of battle and continue meaningful discussion.

The problem with SemVer and humans is that most projects that claim to follow SemVer fall into two categories:

1. Their major version number skyrockets, since every wee breaking change is demanding a major bump. AFAIK that's how SemVer is supposed to work. It's efficient but there is no way to signal a package/app generation upgrade (other than changing the package name like apache-2 which is horrible).

2. Package maintainers want the major version number to reflect package generation. And they fall into two sub-categories:

   a. They hold back breaking changes, including super insignificant ones, and pile them up for an upcoming generation upgrade. This results in weird release schedules that are pulled out of thin air and only exist to worship the SemVer god but not bring convenience to developers or users. When a major release comes, developers have to face with dozens or hundreds of breaking changes at the same time, resulting in unbearable maintenance burden.

   b. They violate semver and release small breaking changes as minor bumps.

   c. Oh, and of course there are projects that do both at the same time.

I believe that the second category are wrong, even though they seem to be much more numerous than the first one. SemVer expects the major number to skyrocket, and all we ask for is to have a separate number to indicate package/app generation. When we have it, all those packages in the second category will be able to stop misusing the major version number.

SemVer is a signaling mechanism by which a package vendor can inform the package consumer whether three types of integration issues may arise with a package update/upgrade:
a) Breaking Changes (major),
b) Non-breaking features (minor),
c) Non-breaking non-features (patches).

It is not about describing the actual "extent of impact" on the package consumer, as this would depends heavily on whether the consumer even uses that part of the vendor's code or how tightly that vendor code is integrated into the consumer's system. The vendor cannot know how a consumer will use their code or if the consumer employs a design pattern. The amount of re-work can vary significantly among different consumers. Therefore, it makes no sense to signal the "extent of impact". But only the type of impact.

The terms "major" and "minor" are often misunderstood as the "extent of impact." Perhaps we need other terms.

The consumer's update strategy (version range) determines which type of impact can occur. The extent of the impact must be determined by the consumer themselves. Currently, a tool (dependency manager) cannot determine this on its own.

In the end, the main reason why SemVer is widely used in our industry is that it has helped create a better "contract" (better understanding) of the signaling between vendor and consumer. It's not perfect yet, but it's better than it was in previous times.

If one were to include the "extent of impact" in SemVer, it would need a mechanism that calculates the extent for the specific consumer project, i.e., an individual calculation.

Possibly, future IDEs could handle this. However, tools like dependency managers are not only used by developers but also by build servers, for which the extent of impact is initially (technically) irrelevant. Why burden them with additional complexity?

If one would do that calculation, then a debate will arise on what is the threshold between "big extent of impact" and "low extent of impact" and maybe if we need more fine grained control. A mess.

I guess the future is to attribute all commits, e.g., to tag all git commits with binary flags:
a) "feature/non-feature,"
b) "breaking/non-breaking change."

Then a tool could aggregate all flags from commit "A" to commit "N." Evaluating if "N" contains a "breaking change" and/or a "feature" will be based on all tags between "A" and "N." In the end, this tool could assign the correct SemVer version to "N." An IDE could help correctly attribute (flag) all commits. That way, you could merge all your commits in different branches, do cherry-picking, etc., while still having "automatic SemVer numbers" in your package release process. This tool should warn, when this assessment for a commit is missing.

As SemVer is a "contract" between vendors and consumers, we should focus on trust and how to improve the quality of SemVer numbers (they should be correct at release time)!

We need to find a way for a consumer to figure out how good the quality process for releases is (spotting breaking changes, spotting features, creating reliable SemVer versions).

Nothing is worse than
a) a vendor silently changes the SemVer release number AFTER releasing the package,
b) a vendor did not spot that a breaking change/heavy bug was creeping into this release (rendering the SemVer guardrails useless).

These tool should help us to assess the quality standards and processes of the vendor and help on defining a good update strategy (version range) related to the assessed level of trust.

We may want to have another tool /IDE feature that helps with accessing the "extent of impact" and further support while changing the consumers code base to reflect that vendor change - but this should stay out of scope for a dependency management tool (or signaling mechanism like SemVer).

Its similar to vulnerability assessment (CVEs). CVEs can signal the potential security risk, but it can not automatic evaluate the "extent of impact" in each consumer package, as it may depend on your config, context or surrounding security measures - the CVE may not even apply to your situation. So signaling of security related information within a SemVer number may comes to mind. You may want to add security related info to SemVer:
a) introduces a security issue (specific CVEs), this release should be skipped (do not update to this version)
b) solves a security issue (specific CVEs)

Your update strategy may become even more complex (compared to SemVer-standalone version ranges):
a) skip release when it contains a vulnerability and alter strategy to: "update-to-last-known-good-version" that matches the version range (wait for a fix)
b) skip release when it contains a vulnerability and alter strategy to: "update-to-major-if-fix-requires-a-breaking-change"
c) if already updated to a problematic package: downgrade-to-last-known-good-version and "wait for fix" that matches the version range
d) if already updated to a problematic package: "update-to-major-if-fix-requires-a-breaking-change"

The above is maybe the "exception policy" to your "general update policy".

The very nature of security issues is that these are spotted AFTER release of a package. Same applies to some bugs. So a (SemVer) version number (at release time), can become obsolete when new discoveries arrive (after release).
I have seen vendors updating the packages content while keeping the exact same SemVer version number (breaking the semantic, when content now has new features or now include breaking changes).
I have also seen vendors revoking packages.
I have also seen vendors deleting / unpublishing packages (which i already installed in my project; causing my teams to become unable to reproduce stuff, if we would not cache external packages). Most of the time theses vendor actions were caused by "AFTER-release-events".

SemVer signaling mechanism comes to its limits when we need to handle "AFTER release events".

At least this info should become closer to the code - to the commit - by attributing (flagging) commits as "CVE-xyz-cause" and "CVE-xyz-fix" for documentation purpose (and to be used by IDEs features and future tools). This would help our tools to "suggest to flag a package as revoked" - to connect the vulnerabilty scanner world with the dependency management world even further.

Dependency manager is a class of tools - but being a dependency manager is a craftsmanship skill of a developer.

@RobSmyth the user for the semantic version is the package manager.

Now there is the problem/solution. Just sounds wrong as the "user" is not the consumer but a manager. Why does the package manager want to know if there was a feature or bug added?

IMO a breaking change is a breaking change and must be a major bump. It signals to consumers to read the release notes to understand the magnitude. Trying to flag large/small is left to the release notes. It does not matter if the version major number is large. If it bumps often then it truely lets users know that there are often breaking changes.

It allows you to set up package compatibility spec for automatic upgrades (depends on trust and product criticality) ... so allow for a bug fix and new feature but not a breaking change. e.g: I'll accept an automatic Microsoft package patch upgrade with little thought.

I find it very useful when consuming products that use it.

As a final note (I hope) ... I find semver very readable (with metadata) and teams I've worked on have found it very helpful. It shows the team and testers:

• The targeted release
• An idea of what it contains compared to last release
• Where is was built (metadata) - build system (controlled), dev box (uncontrolled)
• If a prerelease and what maturity
• Traceability - build number and sha (prerelease and informational version metadata)

The critical question is always who is your consumer and what is a release. A dev team's version number is often very different to the product's marketing version number and name.

I find often that questions of readability is due to it being exposed to the wrong customer. Or ... "why/how are you looking at that version number?"

When a major release comes, developers have to face with dozens or hundreds of breaking changes at the same time, resulting in unbearable maintenance burden

That sounds like a nightmare, but it hasn’t happened to me with libs I work with, so do you have examples?

Most of the major software libraries I use in my work have had breaking changes, and I don’t think there was anything unreasonable or inconvenient about the way they were handled. They bumped the major version number, and there were no surprises. It’s been much better than if I could never upgrade anything without fear that there are minor breaking changes hidden in there that we just happen to use.

It’s been much better than if I could never upgrade anything without fear that there are minor breaking changes hidden in there that we just happen to use.

Yes, knowing whether a breaking change was introduced (simply by looking at the version number) absolutely is useful.

Has anyone been arguing otherwise? If so, in which comment specifically?

My understanding is that the disagreement is merely on whether adding an additional digit at the start is worth it (my opinion: yes), not on whether existing "is this change breaking?" information should be stripped.

---

EDIT: It has been a long time since I read the earlier parts of this thread. I glanced up quickly and it seems as though some of the earlier comments do seem to be suggesting that "is this change breaking?" information is not critical to preserve in the version number.

In which case, my own position would be a hybrid in the context of this thread: I think it's important to keep is-this-breaking information, but think adding a fourth digit to distinguish between major and minor breaking changes is very much worthwhile. (apologies for not noticing this earlier; I must have been thinking of another thread, as there have been multiple on this subject)

Being able to signal a substantially significant upgrade is objectively useless?

OK ... I'll comment. If there is no functional difference in the upgrade then yes it is objectively useless.

If the functionality is a substantial marketing benefit then I would expect marketing to do something with the product name / version.

If however the software and product are the same (your delivering a component) ... then I have at times deviated from semver and bumped the major. But, in those cases I do not consider that to be semver :-). If I formed a contract with the users that I used semver and I bumped the major for a highly valued change then I would expect to be punished :-(

So for semver (software) using major to signal a marketing value impact is objectively problematic. I would expect calls of "you say it is a breaking change but I cannot find a breaking change in the release notes". It is a contract with the consumer.