Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: document non-node_modules-only runtime deprecation #50748

Merged
merged 4 commits into from
Nov 28, 2023
Merged

doc: document non-node_modules-only runtime deprecation #50748

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5c9fe47
doc: document non-node_modules-only runtime deprecation
joyeecheung Nov 15, 2023
4dca046
fixup! doc: document non-node_modules-only runtime deprecation
joyeecheung Nov 20, 2023
5673030
fixup! doc: document non-node_modules-only runtime deprecation
joyeecheung Nov 20, 2023
ae5ecf5
fixup! doc: document non-node_modules-only runtime deprecation
joyeecheung Nov 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 15 additions & 7 deletions doc/api/deprecations.md
View file
Open in desktop
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