Skip to content

Commit

Permalink
doc: document non-node_modules-only runtime deprecation
Browse files Browse the repository at this point in the history
We already have this special kind of runtime deprecation for
Buffer constructors which does not fit into the original
description of runtiem deprecations. Document this kind of
deprecation separately.

PR-URL: #50748
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
  • Loading branch information
joyeecheung authored and targos committed Dec 4, 2023
1 parent 94462d4 commit 30a6f19
Showing 1 changed file with 15 additions and 7 deletions.
22 changes: 15 additions & 7 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,11 @@ Node.js APIs might be deprecated for any of the following reasons:
* An improved alternative API is available.
* Breaking changes to the API are expected in a future major release.

Node.js uses three kinds of Deprecations:
Node.js uses four kinds of deprecations:

* Documentation-only
* Runtime
* Application (non-`node_modules` code only)
* Runtime (all code)
* End-of-Life

A Documentation-only deprecation is one that is expressed only within the
Expand All @@ -25,10 +26,17 @@ deprecations below. Documentation-only deprecations that support that flag
are explicitly labeled as such in the
[list of Deprecated APIs](#list-of-deprecated-apis).

A Runtime deprecation will, by default, generate a process warning that will
be printed to `stderr` the first time the deprecated API is used. When the
[`--throw-deprecation`][] command-line flag is used, a Runtime deprecation will
cause an error to be thrown.
An Application deprecation for only non-`node_modules` code will, by default,
generate a process warning that will be printed to `stderr` the first time
the deprecated API is used in code that's not loaded from `node_modules`.
When the [`--throw-deprecation`][] command-line flag is used, a Runtime
deprecation will cause an error to be thrown. When
[`--pending-deprecation`][] is used, warnings will also be emitted for
code loaded from `node_modules`.

A runtime deprecation for all code is similar to the runtime deprecation
for non-`node_modules` code, except that it also emits a warning for
code loaded from `node_modules`.

An End-of-Life deprecation is used when functionality is or will soon be removed
from Node.js.
Expand Down Expand Up @@ -140,7 +148,7 @@ changes:
description: Documentation-only deprecation.
-->

Type: Runtime (supports [`--pending-deprecation`][])
Type: Application (non-`node_modules` code only)

The `Buffer()` function and `new Buffer()` constructor are deprecated due to
API usability issues that can lead to accidental security issues.
Expand Down

0 comments on commit 30a6f19

Please sign in to comment.