diff options
author | Rich Trott <rtrott@gmail.com> | 2018-06-09 20:16:37 -0700 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2018-06-12 21:04:21 -0700 |
commit | 4c166935ae2eedef10c2a604947eb7703eb15798 (patch) | |
tree | 9f52773112c6e4dc97a0d350c271bf5a4e73bc1f /COLLABORATOR_GUIDE.md | |
parent | 0d79c84a839fb52ccb9e3f0c46541613a1d3db3a (diff) | |
download | android-node-v8-4c166935ae2eedef10c2a604947eb7703eb15798.tar.gz android-node-v8-4c166935ae2eedef10c2a604947eb7703eb15798.tar.bz2 android-node-v8-4c166935ae2eedef10c2a604947eb7703eb15798.zip |
doc: trim deprecation level definition text
Provide more concise explanations of the deprecation levels in
COLLABORATOR_GUIDE.md.
PR-URL: https://github.com/nodejs/node/pull/21241
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Yuta Hiroto <hello@hiroppy.me>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Weijia Wang <starkwang@126.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Diffstat (limited to 'COLLABORATOR_GUIDE.md')
-rw-r--r-- | COLLABORATOR_GUIDE.md | 34 |
1 files changed, 15 insertions, 19 deletions
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index f5ffd35f04..99e8b701c6 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -419,25 +419,20 @@ the future." Node.js uses three Deprecation levels: -* *Documentation-Only Deprecation* refers to elements of the Public API that - should be avoided by developers and that might be staged for a runtime - deprecation in a future Node.js major release. An explicit notice indicating - the deprecation status is added to the API documentation but no functional - changes are implemented in the code. By default there will be no deprecation - warnings emitted for such deprecations at runtime. 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 - switch can be used to escalate such warnings into runtime errors that will - cause the Node.js process to exit. As with Documentation-Only Deprecation, - the documentation for the API must be updated to clearly indicate the - deprecated status. - -* *End-of-life* refers to APIs that have gone through Runtime Deprecation and - are no longer subject to the semantic versioning rules used by the project. +* *Documentation-Only Deprecation*: A deprecation notice is added to the API + documentation but no functional changes are implemented in the code. By + default, there will be no warnings emitted for such deprecations at + runtime. 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*: A warning is emitted at runtime the first time that a + deprecated API is used. The [`--throw-deprecation`][] flag can be used to + escalate such warnings into runtime errors that will cause the Node.js process + to exit. As with Documentation-Only Deprecation, the documentation for the API + must be updated to clearly indicate the deprecated status. + +* *End-of-life*: The API is no longer subject to the semantic versioning rules. Backward-incompatible changes including complete removal of such APIs may occur at any time. @@ -884,6 +879,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` may help. [TSC]: https://github.com/nodejs/TSC [_Deprecation_]: https://en.wikipedia.org/wiki/Deprecation [`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation +[`--throw-deprecation`]: doc/api/cli.md#--throw-deprecation [`node-core-utils`]: https://github.com/nodejs/node-core-utils [backporting guide]: doc/guides/backporting-to-release-lines.md [contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines |