[GH-ISSUE #835] Deprecation should not lead to a minor change in and of itself #2279

New Issue

GiteaMirror · 2026-04-20T10:17:25-05:00

GiteaMirror commented

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

Originally created by @ahenket on GitHub (May 16, 2022).
Original GitHub issue: https://github.com/semver/semver/issues/835

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.

Originally created by @ahenket on GitHub (May 16, 2022). Original GitHub issue: https://github.com/semver/semver/issues/835 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.

GiteaMirror commented

2026-04-20 10:17:26 -05:00

@ljharb commented on GitHub (May 16, 2022):

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.

@ljharb commented on GitHub (May 16, 2022): 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.

GiteaMirror commented

2026-04-20 10:17:26 -05:00

@ahenket commented on GitHub (May 24, 2022):

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.

@ahenket commented on GitHub (May 24, 2022): 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.

GiteaMirror commented

2026-04-20 10:17:27 -05:00

@ljharb commented on GitHub (May 24, 2022):

“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.

@ljharb commented on GitHub (May 24, 2022): “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.

GiteaMirror commented

2026-04-20 10:17:27 -05:00

@ahenket commented on GitHub (May 30, 2022):

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?

@ahenket commented on GitHub (May 30, 2022): 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?

GiteaMirror commented

2026-04-20 10:17:28 -05:00

@ljharb commented on GitHub (May 30, 2022):

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

@ljharb commented on GitHub (May 30, 2022): Docs aren’t part of your api, so i think the distinction is already present.

GiteaMirror commented

2026-04-20 10:17:28 -05:00

@epage commented on GitHub (May 31, 2022):

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.

@epage commented on GitHub (May 31, 2022): 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.

GiteaMirror commented

2026-04-20 10:17:29 -05:00

@ahenket commented on GitHub (May 31, 2022):

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.

@ahenket commented on GitHub (May 31, 2022): 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.

GiteaMirror commented

2026-04-20 10:17:29 -05:00

@jwdonahue commented on GitHub (Sep 16, 2022):

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.

@jwdonahue commented on GitHub (Sep 16, 2022): 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.

GiteaMirror commented

2026-04-20 10:17:29 -05:00

@abdullahjutt302 commented on GitHub (Sep 15, 2024):

Uploading IMG_20240913_205957.jpg…

@abdullahjutt302 commented on GitHub (Sep 15, 2024): > ![Uploading IMG_20240913_205957.jpg…]()

GiteaMirror commented

2026-04-20 10:17:30 -05:00

@abdullahjutt302 commented on GitHub (Sep 15, 2024):

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#2279