[GH-ISSUE #325] What does "issue a new minor release with the deprecation in place" actually mean? #5353

New Issue

GiteaMirror · 2026-06-15T11:40:53-05:00

GiteaMirror commented

2026-06-15 11:40:53 -05:00

Originally created by @farinspace on GitHub (Jul 12, 2016).
Original GitHub issue: https://github.com/semver/semver/issues/325

http://semver.org/#how-should-i-handle-deprecating-functionality

"with the depreciation in place", what does this mean exactly. With notes about the depreciation in place? Console warnings about the depreciation in place?

Just think it should be a little clearer.

Originally created by @farinspace on GitHub (Jul 12, 2016). Original GitHub issue: https://github.com/semver/semver/issues/325 http://semver.org/#how-should-i-handle-deprecating-functionality "with the depreciation in place", what does this mean exactly. With notes about the depreciation in place? Console warnings about the depreciation in place? Just think it should be a little clearer.

GiteaMirror added the question label 2026-06-15 11:40:53 -05:00

GiteaMirror closed this issue

2026-06-15 11:40:55 -05:00

GiteaMirror commented

2026-06-15 11:40:56 -05:00

@Newtopian commented on GitHub (Aug 3, 2016):

Some languages support tags like @deprecated, if it does then there should be a release with this in place. If it does not then check for what are the best practices for that perticular environment about deprecation and make a release with these in place.

If none apply, use best judgement, logs could do the trick, the idea is to communicate as best as possible that these API points will be removed in the next major version. Documentation will do but in addition to that if you can have the code itself communicate this intent all the better.

In ALL cases, the documentation should reflect this. If only for this change there should still be a release with the new documentation changes to communicate the deprecations.

Documentation could be considered as an integral part of the released package, I see no problems bumping a minor release that contains just documentation changes. This is especially true if the documentation is generated from the source as can be the case in many languages / platforms.

@Newtopian commented on GitHub (Aug 3, 2016): Some languages support tags like @deprecated, if it does then there should be a release with this in place. If it does not then check for what are the best practices for that perticular environment about deprecation and make a release with these in place. If none apply, use best judgement, logs could do the trick, the idea is to communicate as best as possible that these API points will be removed in the next major version. Documentation will do but in addition to that if you can have the code itself communicate this intent all the better. In ALL cases, the documentation should reflect this. If only for this change there should still be a release with the new documentation changes to communicate the deprecations. Documentation could be considered as an integral part of the released package, I see no problems bumping a minor release that contains just documentation changes. This is especially true if the documentation is generated from the source as can be the case in many languages / platforms.

GiteaMirror commented

2026-06-15 11:40:56 -05:00

@theetrain commented on GitHub (Jul 6, 2017):

How do deprecating changes affect projects that are on 0.1.0 for example? Would the next version be 0.2.0 or 0.1.1?

@theetrain commented on GitHub (Jul 6, 2017): How do deprecating changes affect projects that are on `0.1.0` for example? Would the next version be `0.2.0` or `0.1.1`?

GiteaMirror commented

2026-06-15 11:40:57 -05:00

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

@farinspace, I would add to @Newtopian's comments that release notes are an especially good place to mention deprecation. Unless you require any further clarification, please close this issue.

@theetrain, how fast do you want to move? How much impact will it have on your early adopters? 0.x.x versions are the wild-west of version semantics. Until you get to your first 1.x.x, your main concerns should be getting to 1.x.x as quickly as possible, without compromising quality. If you require further guidance, please create a new issue.

@jwdonahue commented on GitHub (Dec 1, 2017): @farinspace, I would add to @Newtopian's comments that release notes are an especially good place to mention deprecation. Unless you require any further clarification, please close this issue. @theetrain, how fast do you want to move? How much impact will it have on your early adopters? 0.x.x versions are the wild-west of version semantics. Until you get to your first 1.x.x, your main concerns should be getting to 1.x.x as quickly as possible, without compromising quality. If you require further guidance, please create a new issue.

GiteaMirror commented

2026-06-15 11:40:59 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

Closed as resolved, thanks everyone for contribution 👍
@farinspace If you still have any questions, feel free to re-open

@alexandrtovmach commented on GitHub (Jun 10, 2020): Closed as resolved, thanks everyone for contribution :+1: @farinspace If you still have any questions, feel free to re-open

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#5353