From 2b0fc05da20ac05d833895418e66f933f9756a1e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 18 Feb 2019 20:16:29 -0800 Subject: [PATCH] doc: revise deprecation level explanations in Collaborator Guide Revise deprecation level explanations for scanability and ease of understanding. --- COLLABORATOR_GUIDE.md | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 06840d27e73111..f74bc7eda9550a 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