mirror of
https://github.com/semver/semver.git
synced 2026-07-11 06:53:03 -05:00
[GH-ISSUE #791] FAQ or guidance for changes in underlying dependency stack? #3236
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#3236
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 @arithex on GitHub (Jan 2, 2022).
Original GitHub issue: https://github.com/semver/semver/issues/791
I love semantic versioning and have advocated for it (or something like it) for decades. But one case where I'm never sure how to apply it, is when altering/updating underlying dependencies.
As a simple example, imagine an app or library that used to ship 32- and 64-bit binaries, but now is 64-bit only. Or a graphics library that used to be based on DirectX11 but now is based on DX12.
No new functionality added, and no change in syntax or semantics to the API. Just going forward, it's not going to run on all the systems that it used to.
Does this warrant a major version bump?
@arithex commented on GitHub (Jan 2, 2022):
Related but different: https://github.com/semver/semver/issues/771
@ljharb commented on GitHub (Jan 2, 2022):
Yes, absolutely. To be non-breaking, it must run on all the same systems it used to.
@arithex commented on GitHub (Jan 2, 2022):
I suppose this is why we have Windows 11 now. (newly requires a TPM chip, and DX12 :)
Should there be a FAQ, or update to the description of what constitutes a breaking-change.. I see now, there is a FAQ for "deprecating functionality" that could encompass this.
I think the (potential) cognitive dissonance here is that people think of "API change" differently than "min system requirements". But in reality, the sum total of everything you require (eg. a 64-bit cpu or DX12 gpu) is effectively part of your "API contract".
@ljharb commented on GitHub (Jan 2, 2022):
I don't understand why it needs a FAQ or why this kind of question keeps coming up.
For every possible "someone": if someone is using your software at version X, and they update to version Y, does literally anything no longer work? If anything no longer works, it is a breaking change. If everything still works, it's minor or patch.
It does not matter whatsoever if the reason for the breakage is your own code, or the platform, or a transitive dependency, or the date - if the difference between "everything works" and "something doesn't work" is "they upgraded your software from X to Y" (and, logically, downgrading back to X makes it work again) then Y is a breaking change with respect to X.
How people incorrectly think about the API is irrelevant.
@arithex commented on GitHub (Jan 2, 2022):
Well if a question keeps coming up, it is a FAQ by definition. :P
Seriously, I agree with you -- I think the issue confusing some folks is just terminology. The spec talks entirely in terms of "API" but, the thing which we apply version numbers to, is our concrete implementation of an API, not the abstract definition of the API.
The wording throughout the doc leads one to think in terms of the API definition changing, not just the concrete implementation (eg. support for 32- vs 64-bit) changing.
Eg. the semver introduction says:
But it never really defines the bounds of what "public API" means, or encompasses, the way you did concisely just now.
Just my 2c. I'm a huge proponent of semver and want it to be successfully adopted and consistently applied. That's all.
@ljharb commented on GitHub (Jan 2, 2022):
Fair point on the F in FAQ :-p
the i in API is “interface”; all observable behavior and semantics are part of the interface.
@arithex commented on GitHub (Jan 3, 2022):
Clearly. It's the "AP" part that is not so clear. People can point at their code and say "nothing changed, we don't need to bump the major version".
I don't know any better term than "API contract" to mean "the fundamental contract of compatibility between two software components". So, I merely suggest semver could be strengthened by defining its use of the term "API" to make that broader meaning clear.
At the very least, I think this FAQ entry should be clarified to match what we are saying here.
@jwdonahue commented on GitHub (Jan 10, 2022):
In many cases, dependency nets and supported platforms will certainly be in play when considering whether to bump the major version, but this is not the case in every environment and the SemVer FAQ literally states that dependencies should not be considered.
@arithex do a little research, you'll find this topic has been ground to dust over the years and some really good proposed changes to the FAQ in this regard, have been allowed to rot on the vine. @ljharb would have us believe that if there is anyone in the world who could claim your changes will break them, you must take the major version bump, but the FAQ says the opposite and changing that to meet @ljharb's definition would be considered by many, to be a breaking change to SemVer.
The reality is, you publish into an ecosystem that has norms of behavior, and there are varying levels of cost involved in violating those norms. Publishers should apply a modicum of common sense when interpreting the spec, and how it applies to their changes.
@jwdonahue commented on GitHub (Jan 10, 2022):
@ljharb wrote:
Bugs can be observable behaviors. There is such a thing as pushing a concept too far.
The spec says that the publisher defines whatever the API is. That means they can say the version number applies only to method signatures without regard to implementation behaviors (pure interfaces for instance). They can say it applies to everything in a package, except the package manifest. As far as the SemVer spec is concerned, it is entirely up to the publisher what their "API" is. Once they define that, they have committed to making reasonable efforts to conform to the defined version syntax and semantics.
@ljharb commented on GitHub (Jan 10, 2022):
Yes, which is why intention matters.
Put another way, unless an observable behavior is documented to not be part of the API, it is part of it.
@jwdonahue commented on GitHub (Jan 10, 2022):
Not according to the spec. The spec says only that which you have defined, by whatever means, is part of your API. You can make no claims regarding my unstated intentions, any more than I can on yours. If I observe that you stumbled while walking, should I assume you did so intentionally? What if you fall and crack your head open? Should I leave you there, on the assumption that you intended to lay there bleeding on the ground? I think not.
We have to apply a reasonableness test to observed behaviors in order to make a good estimate of intent.
If a publisher clearly states that they do not support every possible someone updating from X to Y, then while it may be true for that someone that they are broken, the publisher is under no obligation to force a major version bump. For instance, if a behavior is brought to the publishers attention that they or someone else considers a bug, they are within their rights to fix it with a patch level bump, even if there's a handful of consumers out there who are subsequently broken as a result.
How much pain a publisher is willing to inflict on their consumers is a function of their perceived cost for bumping the major version, balanced by how much back-lash they are willing accept from their customers.
@Shakallasombra commented on GitHub (Jul 31, 2022):
Agregame