mirror of
https://github.com/semver/semver.git
synced 2026-07-10 19:50:47 -05:00
[GH-ISSUE #508] Clarification on when deprecated API should/can be removed. #7350
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#7350
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 @jake-at-work on GitHub (Apr 5, 2019).
Original GitHub issue: https://github.com/semver/semver/issues/508
If I deprecate a v1.x defined API 1.5.0, must the corresponding symbols be removed, or otherwise inaccessible, in 2.0.0 or can this take place anywhere in the 2.x releases? Asked another way, is the only time it is acceptable to removed the previously deprecated symbols is in the Major.Zero release, such that if not removed at this time it may not be removed until the next Major.Zero release? Or, is it acceptable to remove the previously deprecated symbols any time at or after the Major.Zero release?
The question has was raised because how does the interpretation of no backwards incompatible changes in minor release apply when deprecated symbols are left in the next major release, the consumer continues to access the deprecated API symbols from the this new major release, but then at some point in a minor they are finally removed.
I interpret the documentation of API to supersede the accessibility of the symbols, such that after major release any previously deprecated API is no longer valid API, regardless the symbol's accessibility. In this form the removal of the symbols can take place at any point at or after the Major.Zero release and the consumer is expected to remove use of deprecated symbols when updating to this or subsequent releases.
I know other believe that symbol accessibility supersedes the documentation or that the documentation of deprecation survives the major if the symbols and documentation of the deprecation are not also removed. In this form then any symbol removal can only occur at the Major.Zero release thus preventing the consumer from inadvertently continuing to use deprecated symbols.
Thoughts and opinions are wanted.
Thanks,
Jake
@ljharb commented on GitHub (Apr 5, 2019):
I would be very upset and surprised if something was removed in a non major.zero release in any project i depended on, regardless of documentation.
@runeimp commented on GitHub (Apr 6, 2019):
If you deprecate anything it should be noted and easily found by your API users. When you remove accessibility and documentation it should be stated well ahead of time. There should also be enough lead time that users of the API have reasonable time for their implementation to be updated. Usually 6 months to a year or more in general if the API is in a reasonable amount of usage. But in any case it's your choice when to remove parts of an API. Just try not to alienate your API users in what may appear on their end as "having the rug pulled out from under them." It helps greatly to understand your user base. If you're dealing with fortune 500 companies or tens of thousands of users your lead time and communication about removal of functionality better be exceptional. If it's just a few hundred users "playing around" with the API it's more likely less critical, in a very general sense.
@asdkant commented on GitHub (Jun 21, 2019):
This language is a bit unclear:
What it looks like the minor version in this case should contain is deprecation warnings, not the deprecation itself.
@ljharb commented on GitHub (Jun 21, 2019):
Deprecation is the warning; removal is what you do after it’s deprecated.
@jwdonahue commented on GitHub (Aug 16, 2019):
If you remove something that had been publicly available in an earlier release, you must bump the major version number. The spec says you must have at least one minor version that includes the deprecation notice prior to removal. It does not mention time, nor does it provide a strict definition of API. In the universe defined by the spec, time, if it can be assumed at all, is marked by the availability of each new unique version string, and is non-monotonic (1.0.1 can happen after 2.5.9).
The FAQ clearly states what the spec only implies:
How should I handle deprecating functionality?
Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. 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.
There is nothing in the spec or the FAQ that says the next major release must remove said deprecated functionality. If you want or need to continue propagating the deprecation notice for multiple minor or major versions, that is your prerogative. Maybe the notice in 1.9.0 says that function X will be removed in major release 20.0.0 or the first major release in the year YYYY. All of that is up to you.
@jwdonahue commented on GitHub (Jan 17, 2020):
@pivotal-jbarrett, unless you have further questions, or intend to issue a related PR, please close this issue at your earliest possible convenience.