mirror of
https://github.com/nodejs/node.git
synced 2026-10-14 10:26:26 -04:00
doc: deprecation clarifications
PR-URL: https://github.com/nodejs/node/pull/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>
This commit is contained in:
1 parent
cd5f353405
commit
7238b92773
1 file changed
+11
-9
+11
-9
@@ -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:
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user