[GH-ISSUE #257] Deprecation of APIs and introdcuing backwards incompatible API changes in semantic versioning #1047

New Issue

GiteaMirror · 2026-04-16T10:15:09-05:00

GiteaMirror commented

2026-04-16 10:15:09 -05:00

Originally created by @gnijuohz on GitHub (Jun 4, 2015).
Original GitHub issue: https://github.com/semver/semver/issues/257

From the document, I understand that after version 1.0.0, deprecation of APIs (without introducing any backwards incompatible API changes) should increase the minor version number and introducing backwards incompatible API changes should increase the major version number.

It also talks about deprecating functionality in the FAQ section. But it doesn't say something like this, you should deprecate an API if you are going to delete it. (which I think is a good practice)

So I suppose as long as one conforms to the specification (i.e., increase the major release version number), backwards incompatible API changes can be introduced without related APIs being deprecated first? That doesn't sound good.

Should there be some rule preventing sudden changes? Is it out of the scope of this specification? should it be something that's up to the developers?

Originally created by @gnijuohz on GitHub (Jun 4, 2015). Original GitHub issue: https://github.com/semver/semver/issues/257 From the document, I understand that after version 1.0.0, deprecation of APIs (without introducing any backwards incompatible API changes) should increase the minor version number and introducing backwards incompatible API changes should increase the major version number. It also talks about deprecating functionality in the FAQ section. But it doesn't say something like this, you should deprecate an API if you are going to delete it. (which I think is a good practice) So I suppose as long as one conforms to the specification (i.e., increase the major release version number), backwards incompatible API changes can be introduced without related APIs being deprecated first? That doesn't sound good. Should there be some rule preventing sudden changes? Is it out of the scope of this specification? should it be something that's up to the developers?

GiteaMirror closed this issue

2026-04-16 10:15:10 -05:00

GiteaMirror commented

2026-04-16 10:15:11 -05:00

@stecman commented on GitHub (Jun 9, 2015):

@gnijuohz - the FAQ about deprecating functionality already has a sentence to the effect of "you should deprecate an API if you are going to delete it":

Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

I'm pretty sure that covers the case you're describing. I presume this is in the FAQs rather than in the spec definition as it's more of a "good neighbour" thing to do, rather than something that is required for semver to work.

@stecman commented on GitHub (Jun 9, 2015): @gnijuohz - the [FAQ about deprecating functionality](https://github.com/mojombo/semver/blob/05e793243bcab8275e61d6d84b2d742c737593e8/semver.md#how-should-i-handle-deprecating-functionality) already has a sentence to the effect of _"you should deprecate an API if you are going to delete it"_: > Before you completely remove the functionality in a new major release **there should be at least one minor release that contains the deprecation** so that users can smoothly transition to the new API. I'm pretty sure that covers the case you're describing. I presume this is in the FAQs rather than in the spec definition as it's more of a "good neighbour" thing to do, rather than something that is required for semver to work.

GiteaMirror commented

2026-04-16 10:15:12 -05:00

@jwdonahue commented on GitHub (Dec 8, 2017):

@gnijuohz, unless you have additional questions on this matter, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Dec 8, 2017): @gnijuohz, unless you have additional questions on this matter, please close this issue at your earliest possible convenience.

GiteaMirror referenced this issue

2026-04-16 10:55:48 -05:00

[GH-ISSUE #1047] fakelley #1509

GiteaMirror referenced this issue

2026-04-20 10:23:56 -05:00

[GH-ISSUE #1047] fakelley #2376

GiteaMirror referenced this issue

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

[GH-ISSUE #1047] fakelley #3358

GiteaMirror referenced this issue

2026-06-13 13:18:25 -05:00

[GH-ISSUE #1047] fakelley #4887