Skip to content

doc: deprecation clarifications #19522

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jasnell wants to merge 3 commits into from
Closed

doc: deprecation clarifications #19522

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11c3a41
doc: deprecation clarifications
jasnell Mar 21, 2018
cb84aaa
[Squash] address feedback
jasnell Mar 22, 2018
4c9c281
[Squash] nits
jasnell Mar 24, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[Squash] address feedback
  • Loading branch information
@jasnell
jasnell authored Mar 22, 2018
commit cb84aaa73217565adfdd67f483f531b247207731
22 changes: 11 additions & 11 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -406,8 +406,8 @@ recommended but not required.
__Deprecation__ refers to the identification of Public APIs that should no
longer be used.

Once specific bits of code are marked as being Deprecated, they are no longer
covered by the typical current or Long Term Support policies.
Once APIs are Deprecated, they are no longer covered by the current or
[Long Term Support][LTS] policies.
Copy link
Copy Markdown
Member

@Trott Trott Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a link to a repository that doesn't seem to have any policies. Honest, I'm not sure what this sentence means. If it's only about the fact that breaking changes can happen with deprecated APIs, then that's covered later in this doc and much more clearly than here. If it's about something else...what is it?

Copy link
Copy Markdown
Member

@Trott Trott Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(I think you can remove this sentence entirely TBQH.)


Node.js uses three Deprecation levels:

Expand All @@ -416,9 +416,9 @@ Node.js uses three Deprecation levels:
notice indicating the deprecated status is added to the API documentation
but no functional changes are implemented in the code. There will be no
runtime deprecation warnings emitted for such deprecations by default.
Documentation-only deprecations may trigger an opt-in only runtime warning
when Node.js is launched with the [`--pending-deprecation`][] flag (or its
alternative, `NODE_PENDING_DEPRECATION=1` environment variable).
Documentation-only deprecations may trigger an runtime warning when Node.js
Copy link
Copy Markdown
Member

@Trott Trott Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

an runtime -> a runtime

is launched with the [`--pending-deprecation`][] flag, or the
Copy link
Copy Markdown
Member

@Trott Trott Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

launched -> started

remove comma after flag

`NODE_PENDING_DEPRECATION=1` environment variable is set.

* *Runtime Deprecation* refers to the use of process warnings emitted at
runtime the first time that a deprecated API is used. A command-line
Expand All @@ -428,9 +428,9 @@ Node.js uses three Deprecation levels:
deprecated status.

* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
are no longer subject to the semantic-versioning and support policies used by
the project. Backward-incompatible changes or even complete removal of such
code may occur at any time.
are no longer subject to the semantic versioning and [support policies](LTS)
Copy link
Copy Markdown
Member

@Trott Trott Mar 22, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As above, the link here doesn't provide clarity. Can you be specific about some aspect of deprecated APIs that is different than everything else other than the semantic version stuff? If not, let's remove and support policies.

used by the project. Backward-incompatible changes including complete removal
of such APIs may occur at any time.

Documentation-Only Deprecations may be handled as semver-minor or semver-major
changes. Such deprecations have no impact on the successful operation of running
Expand All @@ -456,9 +456,8 @@ a Runtime Deprecation until the next major release.)

No API can be moved to End-of-life without first having gone through a
Runtime Deprecation cycle. However, there is no requirement that deprecated
code must progress ultimately to *End-of-Life*. It is possible, and at times
preferable, for code that is documentation-only or runtime deprecated to
remain so indefinitely.
code must progress ultimately to *End-of-Life*. Documentation-only and runtime
deprecations may remain indefinitely.

A best effort will be made to communicate pending deprecations and associated
mitigations with the ecosystem as soon as possible (preferably before the pull
Expand Down Expand Up @@ -838,3 +837,4 @@ LTS working group and the Release team.
[node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
["Merge Pull Request"]: https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-github
[flaky tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22
[LTS]: https://github.com/nodejs/Release