Skip to content

Commit

Permalink
doc: clearer doc-only deprecations
Browse files Browse the repository at this point in the history
Explicitely mention that a documentation only deprecation does not
always imply that it will be staged for deprecation in a future
Node.js major release. It is mainly there to tell developers that
a specific API should be avoided.

PR-URL: nodejs#20381
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
BridgeAR committed May 7, 2018
1 parent 974df9c commit 28a54cb
Showing 1 changed file with 9 additions and 8 deletions.
17 changes: 9 additions & 8 deletions COLLABORATOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -416,14 +416,15 @@ longer be used.

Node.js uses three Deprecation levels:

* *Documentation-Only Deprecation* refers to elements of the Public API that are
being staged for deprecation in a future Node.js major release. An explicit
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 Node.js
is started with the [`--pending-deprecation`][] flag or the
`NODE_PENDING_DEPRECATION=1` environment variable is set.
* *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
Expand Down

0 comments on commit 28a54cb

Please sign in to comment.