diff options
| author | Rich Trott <rtrott@gmail.com> | 2019-02-18 20:16:29 -0800 |
|---|---|---|
| committer | Rich Trott <rtrott@gmail.com> | 2019-02-20 22:06:47 -0800 |
| commit | 70b13c28c940725a953168105ce55c0966fc0a20 (patch) | |
| tree | df806d119f096c343c1dce6e34bede0086a72a10 /COLLABORATOR_GUIDE.md | |
| parent | 042e2640e68832554733377245a3d6d4f76a7002 (diff) | |
| download | android-node-v8-70b13c28c940725a953168105ce55c0966fc0a20.tar.gz android-node-v8-70b13c28c940725a953168105ce55c0966fc0a20.tar.bz2 android-node-v8-70b13c28c940725a953168105ce55c0966fc0a20.zip | |
doc: revise deprecation level explanations in Collaborator Guide
Revise deprecation level explanations for scanability and ease of
understanding.
PR-URL: https://github.com/nodejs/node/pull/26197
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Yuta Hiroto <hello@hiroppy.me>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: James M Snell <jasnell@gmail.com>
Diffstat (limited to 'COLLABORATOR_GUIDE.md')
| -rw-r--r-- | COLLABORATOR_GUIDE.md | 37 |
1 files changed, 19 insertions, 18 deletions
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 06840d27e7..f74bc7eda9 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -319,24 +319,25 @@ guide](https://github.com/nodejs/node/blob/master/doc/guides/adding-new-napi-api ### Deprecations -Node.js uses three [Deprecation][] levels: - -* *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. +Node.js uses three [Deprecation][] levels. For all deprecated APIs, the API +documentation must state the deprecation status. + +* Documentation-Only Deprecation + * A deprecation notice appears in the API documentation. + * There are no functional changes. + * By default, there will be no warnings emitted for such deprecations at + runtime. + * May cause a runtime warning with the [`--pending-deprecation`][] flag or + `NODE_PENDING_DEPRECATION` environment variable. + +* Runtime Deprecation + * Emits a warning at runtime on first use of the deprecated API. + * If used with the [`--throw-deprecation`][] flag, will throw a runtime error. + +* 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. Documentation-Only Deprecations may be handled as semver-minor or semver-major changes. Such deprecations have no impact on the successful operation of running |