[GH-ISSUE #1010] Semver 3.0.0: require opt-in #3339

New Issue

GiteaMirror · 2026-04-25T17:42:06-05:00

GiteaMirror commented

2026-04-25 17:42:06 -05:00

Originally created by @conartist6 on GitHub (Mar 19, 2024).
Original GitHub issue: https://github.com/semver/semver/issues/1010

To address a concern I have, many people in the real world are "following the semver spec" in an unversioned way, e.g. they publish packages with three-digit version numbers to npm, and it is not immediately clear whether an individual publishing such a package has read the semver spec and agrees to behave in the manner prescribed by the spec.

I would suggest that the 3.0 spec require the presence of some indication that the spec is being followed by the package author, such as the presence of a semver-3.0.0.md file, before it can be considered effective as an agreement.

Originally created by @conartist6 on GitHub (Mar 19, 2024). Original GitHub issue: https://github.com/semver/semver/issues/1010 To address a concern I have, many people in the real world are "following the semver spec" in an unversioned way, e.g. they publish packages with three-digit version numbers to npm, and it is not immediately clear whether an individual publishing such a package has read the semver spec and agrees to behave in the manner prescribed by the spec. I would suggest that the 3.0 spec require the presence of some indication that the spec is being followed by the package author, such as the presence of a `semver-3.0.0.md` file, before it can be considered effective as an agreement.

GiteaMirror closed this issue

2026-04-25 17:42:07 -05:00

GiteaMirror commented

2026-04-25 17:42:08 -05:00

@ljharb commented on GitHub (Mar 19, 2024):

A spec isn't an agreement, but it makes sense to me for an ecosystem to have a way for a package author to indicate a semver spec version - altho I'm not sure that's something that can be anything but a "should" in this spec.

@ljharb commented on GitHub (Mar 19, 2024): A spec isn't an agreement, but it makes sense to me for an ecosystem to have a way for a package author to indicate a semver spec version - altho I'm not sure that's something that can be anything but a "should" in this spec.

GiteaMirror commented

2026-04-25 17:42:09 -05:00

@conartist6 commented on GitHub (Mar 19, 2024):

A spec can offer a proposed contract: "if you behave in this way, in return you will get this much safety". Because it's not enforced or enforceable, it only works to the extent that both parties want to behave in the way described. Even so, it's the specific terms laid out that are functioning like an effective contract -- a social contract if you will -- because their fulfillment causes both parties to get what they want out of the arrangement.

@conartist6 commented on GitHub (Mar 19, 2024): A spec can offer a proposed contract: "if you behave in this way, in return you will get this much safety". Because it's not enforced or enforceable, it only works to the extent that both parties want to behave in the way described. Even so, it's the specific terms laid out that are functioning like an effective contract -- a social contract if you will -- because their fulfillment causes both parties to get what they want out of the arrangement.

GiteaMirror commented

2026-04-25 17:42:09 -05:00

@ljharb commented on GitHub (Mar 19, 2024):

Sure, and the mechanism you propose, built into an ecosystem, would be the first time I'm aware of where a package author can explicitly communicate that such that "agreement" is even possible. Currently, at least in the ecosystems I'm familiar with, it's not possible.

@ljharb commented on GitHub (Mar 19, 2024): Sure, and the mechanism you propose, built into an ecosystem, would be the first time I'm aware of where a package author can explicitly communicate that such that "agreement" is even possible. Currently, at least in the ecosystems I'm familiar with, it's not possible.

GiteaMirror commented

2026-04-25 17:42:10 -05:00

@conartist6 commented on GitHub (Mar 19, 2024):

I found out about semver from projects that were explicit about using it, of which there were and are plenty. A quick search says there are around 400,000 backlinks to https://semver.org on the internet. I read the semver spec after clicking on one those links, and afterwords I understood my relationship to the person publishing that code. I understood that I could receive security patches and new features without risking breakage so long as I agreed to read the documentation and not rely on internals, bugs, or unspecified behaviors.

What is it then that is not possible?

@conartist6 commented on GitHub (Mar 19, 2024): I found out about semver from projects that were explicit about using it, of which there were and are plenty. A quick search says there are around 400,000 backlinks to https://semver.org on the internet. I read the semver spec after clicking on one those links, and afterwords I understood my relationship to the person publishing that code. I understood that I could receive security patches and new features without risking breakage so long as I agreed to read the documentation and not rely on internals, bugs, or unspecified behaviors. What is it then that is not possible?

GiteaMirror commented

2026-04-25 17:42:12 -05:00

@ljharb commented on GitHub (Mar 20, 2024):

Programmatically conveying that the package follows a specific version of the semver spec. Putting it in prose assumes that people read prose, which is not a reasonable assumption.

@ljharb commented on GitHub (Mar 20, 2024): Programmatically conveying that the package follows a specific version of the semver spec. Putting it in prose assumes that people read prose, which is not a reasonable assumption.

GiteaMirror commented

2026-04-25 17:42:13 -05:00

@steveklabnik commented on GitHub (Mar 25, 2024):

I don't think that changes as big as this are something that semver itself can make. If a tool thinks this is a good idea, they can mandate this on top of it, but in general, tools that use semver expect their users to use semver. if a user disregards this, that's at their own peril.

@steveklabnik commented on GitHub (Mar 25, 2024): I don't think that changes as big as this are something that semver itself can make. If a tool thinks this is a good idea, they can mandate this on top of it, but in general, tools that use semver expect their users to use semver. if a user disregards this, that's at their own peril.

GiteaMirror commented

2026-04-25 17:42:14 -05:00

@conartist6 commented on GitHub (Mar 25, 2024):

I guess I don't see how the spec works at all then. The spec seems to guarantee to package consumers how they can expect package authors to behave.

If the package author has never read the spec, how is any safety or system achieved? Why as a consumer should I trust a guarantee a spec author makes about how the package author will behave?

@conartist6 commented on GitHub (Mar 25, 2024): I guess I don't see how the spec works at all then. The spec seems to guarantee to package consumers how they can expect package authors to behave. If the package author has never read the spec, how is any safety or system achieved? Why as a consumer should I trust a guarantee a spec author makes about how the package author will behave?

GiteaMirror commented

2026-04-25 17:42:14 -05:00

@steveklabnik commented on GitHub (Mar 29, 2024):

Services like npm say "hey we use semver to resolve versions of your packages." By publishing to a registry like npm, the author says they're going to use semver. If they don't, that's their own error, and asking them to also put a file isn't going to change that.

@steveklabnik commented on GitHub (Mar 29, 2024): Services like npm say "hey we use semver to resolve versions of your packages." By publishing to a registry like npm, the author says they're going to use semver. If they don't, that's their own error, and asking them to *also* put a file isn't going to change that.

GiteaMirror commented

2026-04-25 17:42:15 -05:00

@conartist6 commented on GitHub (Mar 29, 2024):

There's a deep logical inconsistency inherent in saying that "they implicitly agreed to whatever the package manager said to do" while then also arguing something like "all past behavior should be interpreted in light of this future definition".

The npm docs (stilll) say:

Version must be parseable by node-semver, which is bundled with npm as a dependency. (npm install semver to use it yourself.)

More on version numbers and ranges at semver.

and then under that documentation for the ^:

Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X.

Many authors treat a 0.x version as if the x were the major "breaking-change" indicator.

Caret ranges are ideal when an author may make breaking changes between 0.2.4 and 0.3.0 releases, which is a common practice. However, it presumes that there will not be breaking changes between 0.2.4 and 0.2.5. It allows for changes that are presumed to be additive (but non-breaking), according to commonly observed practices.

This directs consumer of packages how to behave but not producers. The only official guidance to producers was and is the 2.0 semver spec

@conartist6 commented on GitHub (Mar 29, 2024): There's a deep logical inconsistency inherent in saying that "they implicitly agreed to whatever the package manager said to do" while then also arguing something like "all past behavior should be interpreted in light of this future definition". The npm docs (stilll) say: > Version must be parseable by [node-semver](https://github.com/isaacs/node-semver), which is bundled with npm as a dependency. (npm install semver to use it yourself.) > > More on version numbers and ranges at [semver](https://docs.npmjs.com/cli/v6/using-npm/semver). and then under that documentation for the `^`: > Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X. > > Many authors treat a 0.x version as if the x were the major "breaking-change" indicator. > > Caret ranges are ideal when an author may make breaking changes between 0.2.4 and 0.3.0 releases, which is a common practice. However, it presumes that there will not be breaking changes between 0.2.4 and 0.2.5. It allows for changes that are presumed to be additive (but non-breaking), according to commonly observed practices. This directs consumer of packages how to behave but not producers. The only official guidance to producers was and is the 2.0 semver spec

GiteaMirror commented

2026-04-25 17:42:15 -05:00

@ljharb commented on GitHub (Mar 29, 2024):

Feel free to file an issue for npm to clear up their docs - I agree they're incorrect, because the implementation reality (since npm's inception) differs.

@ljharb commented on GitHub (Mar 29, 2024): Feel free to file an issue for npm to clear up their docs - I agree they're incorrect, because the implementation reality (since npm's inception) differs.

GiteaMirror commented

2026-04-25 17:42:16 -05:00

@conartist6 commented on GitHub (Mar 30, 2024):

The npm docs say (paraphrased):

"Here is how package maintainers may behave"
"Here are the ways to specify your own behavior"

Could you please point me to even one way in which these docs don't accurately and correctly describe the situation?

@conartist6 commented on GitHub (Mar 30, 2024): The npm docs say (paraphrased): - "Here is how package maintainers may behave" - "Here are the ways to specify your own behavior" Could you please point me to even one way in which these docs don't accurately and correctly describe the situation?

GiteaMirror commented

2026-04-25 17:42:17 -05:00

@conartist6 commented on GitHub (Mar 30, 2024):

It seems to me that your argument would be consistent with NPM having replaced the implementation of ~ with the implementation of ^. I'd be much more likely to support your argument if this had been the case, but it is not.

@conartist6 commented on GitHub (Mar 30, 2024): It seems to me that your argument would be consistent with NPM having replaced the implementation of `~` with the implementation of `^`. I'd be much more likely to support your argument if this had been the case, but it is not.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#3339