Skip to content

Commit

Permalink
doc: deprecation clarifications
Browse files Browse the repository at this point in the history
PR-URL: #19522
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
  • Loading branch information
jasnell authored and targos committed Apr 3, 2018
1 parent 152a86c commit 5149e18
Showing 1 changed file with 11 additions and 9 deletions.
20 changes: 11 additions & 9 deletions COLLABORATOR_GUIDE.md
Expand Up @@ -408,10 +408,8 @@ recommended but not required.

### Deprecations

_Deprecation_ refers to the identification of Public APIs that should no longer
be used and that may be removed or modified in backward-incompatible ways in
a future major release of Node.js. Deprecation may be used with internal APIs if
there is expected impact on the user community.
__Deprecation__ refers to the identification of Public APIs that should no
longer be used.

Node.js uses three Deprecation levels:

Expand All @@ -420,9 +418,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 a runtime warning when launched
with [`--pending-deprecation`][] flag (or its alternative,
`NODE_PENDING_DEPRECATION=1` environment variable).
Documentation-only deprecations may trigger a runtime warning when Node.js
is started with the [`--pending-deprecation`][] flag or the
`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 @@ -432,7 +430,9 @@ Node.js uses three Deprecation levels:
deprecated status.

* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
are ready to be removed from Node.js entirely.
are no longer subject to the semantic versioning rules 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 @@ -457,7 +457,9 @@ Deprecations may land in a Node.js minor release but must not be upgraded to
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.
Runtime Deprecation cycle. However, there is no requirement that deprecated
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

0 comments on commit 5149e18

Please sign in to comment.