Deprecation should not lead to a minor change in and of itself

[ahenket]

Pertains to: https://semver.org/#spec-item-7

Deprecation is a meta data thing that applies to the specification/API/product, but does not affect a single character in it. To date I've never seen any product that has an updated version number just because it is sunsetted.

A change in the minor version signals a change of some kind. Usually a new feature. If all it does is introduce deprecation then imagine the disappointment when you 'upgrade' to that new version.

The iPhone 6 also did not become iPhone 6.1 when Apple stopped supporting it. I think "deprecation equals new minor version" should not be in the semver specification, unless combined with other changes e.g. a last round of bug fixes before you stop supporting it.

[ljharb]

node does this, in fact, for runtime deprecation warnings. Deprecation is part of a version and an API when it involves runtime behavior - like printing a warning.

[ahenket]

Deprecation in and of itself does not affect any runtime behavior. It just signals what is going to happen in some future version, allowing implementers time to consider their options. I doubt that node.js ever updated to a new minor just to signal deprecation of a part: for us deprecation of a given standard version when the new major version was already out there was the use case. There was a grace period for using the older version which was extended a couple of times, but now finally was solidified.

So for this documentation/specification we tried updating the version number to a new minor just last month and found ourselves spending many man hours explaining that we did not in fact change anything except that part. Hence the plea to go from SHALL to something less like SHOULD or MAY to allow room for contexts where it leads to more issue than it solves. This would still allow node.js to do what they do.

[ljharb]

“deprecation” isn’t a single thing; the term is incredibly overloaded.

I agree if your deprecation is docs-only, that it’s semver-patch. node does this as well.

[ahenket]

Is it conceivable to reflect that distinction in a next version of semver? Is there a maintenance process to follow, or does this issue need upvoting from X people, ... other?

[ljharb]

Docs aren’t part of your api, so i think the distinction is already present.

[epage]

I disagree. I read the statement straight as-is and applied it to my main language's notion of deprecation (Rust) which only provides compile time warnings to my direct dependents.

I also have seen enough people being pedantic about semver that clarifying things will help make those conversations go more smoothly.

[ahenket]

So then it may be a question of interpretation. We have adopted semver for our documentation purposes and communicated to our implementers: expect what semver says to expect. Did we misinterpret that semver could be of use in our context? There's also the similar effort going on through #609. It seems relevant to know if the scope of semver extends into documentation or not.

[jwdonahue]

The intro to the spec says that you define what is part of your "API" and mentions docs explicitly.

In C/C++ warnings can be explicitly emitted from code for things like deprecation notices, but many build environments enable a feature that treats all warnings as errors. The spec fails to cover many of the contingencies around deprecation. While an attempt was made to be language agnostic, I suspect the original author had Java in mind when they wrote it.

I am in full agreement that MUST is too strong and suspect that SHOULD is also. MAY seems more appropriate.