nodejs
/
node
mirror of https://github.com/nodejs/node.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: make stability labels more consistent 

PR-URL: https://github.com/nodejs/node/pull/57516
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
This commit is contained in:
Antoine du Hamel 2025-03-23 16:58:20 +01:00
parent b4576a6f57
commit 717c44dead
No known key found for this signature in database
GPG Key ID: 21D900FFDB233756
14 changed files with 114 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/buffer.md
View File

@ -5356,8 +5356,6 @@ instance.
deprecated: v6.0.0
-->
> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead.
* `size` {integer} The desired length of the new `SlowBuffer`.
See [`Buffer.allocUnsafeSlow()`][].

34
doc/api/cli.md
View File

@ -61,6 +61,8 @@ changes:
Node.js options as well, in addition to V8 options.
-->
> Stability: 2 - Stable
All options, including V8 options, allow words to be separated by both
dashes (`-`) or underscores (`_`). For example, `--pending-deprecation` is
equivalent to `--pending_deprecation`.
@ -199,8 +201,6 @@ changes:
description: Paths delimited by comma (`,`) are no longer allowed.
-->
> Stability: 2 - Stable.
This flag configures file system read permissions using
the [Permission Model][].
@ -244,8 +244,6 @@ changes:
description: Paths delimited by comma (`,`) are no longer allowed.
-->
> Stability: 2 - Stable.
This flag configures file system write permissions using
the [Permission Model][].
@ -453,8 +451,6 @@ changes:
description: The flag is no longer experimental.
-->
> Stability: 2 - Stable
Provide custom [conditional exports][] resolution conditions.
Any number of custom string condition names are permitted.
@ -480,8 +476,6 @@ changes:
description: The `--cpu-prof` flags are now stable.
-->
> Stability: 2 - Stable
Starts the V8 CPU profiler on start up, and writes the CPU profile to disk
before exit.
@ -518,8 +512,6 @@ changes:
description: The `--cpu-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the directory where the CPU profiles generated by `--cpu-prof` will
be placed.
@ -538,8 +530,6 @@ changes:
description: The `--cpu-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the sampling interval in microseconds for the CPU profiles generated
by `--cpu-prof`. The default is 1000 microseconds.
@ -555,8 +545,6 @@ changes:
description: The `--cpu-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the file name of the CPU profile generated by `--cpu-prof`.
### `--diagnostic-dir=directory`
@ -1294,8 +1282,6 @@ changes:
description: The `--heap-prof` flags are now stable.
-->
> Stability: 2 - Stable
Starts the V8 heap profiler on start up, and writes the heap profile to disk
before exit.
@ -1323,8 +1309,6 @@ changes:
description: The `--heap-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the directory where the heap profiles generated by `--heap-prof` will
be placed.
@ -1343,8 +1327,6 @@ changes:
description: The `--heap-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the average sampling interval in bytes for the heap profiles generated
by `--heap-prof`. The default is 512 \* 1024 bytes.
@ -1360,8 +1342,6 @@ changes:
description: The `--heap-prof` flags are now stable.
-->
> Stability: 2 - Stable
Specify the file name of the heap profile generated by `--heap-prof`.
### `--heapsnapshot-near-heap-limit=max_count`
@ -1906,8 +1886,6 @@ changes:
description: Permission Model is now stable.
-->
> Stability: 2 - Stable.
Enable the Permission Model for current process. When enabled, the
following permissions are restricted:
@ -2220,8 +2198,6 @@ changes:
`PATH` environment variable accordingly.
-->
> Stability: 2 - Stable
This runs a specified command from a package.json's `"scripts"` object.
If a missing `"command"` is provided, it will list the available scripts.
@ -3019,8 +2995,6 @@ changes:
description: Test runner now supports running in watch mode.
-->
> Stability: 2 - Stable
Starts Node.js in watch mode.
When in watch mode, changes in the watched files cause the Node.js process to
restart.
@ -3049,8 +3023,6 @@ changes:
description: Watch mode is now stable.
-->
> Stability: 2 - Stable
Starts Node.js in watch mode and specifies what paths to watch.
When in watch mode, changes in the watched paths cause the Node.js process to
restart.
@ -3093,6 +3065,8 @@ instances.
## Environment variables
> Stability: 2 - Stable
### `FORCE_COLOR=[1, 2, 3]`
The `FORCE_COLOR` environment variable is used to

12
doc/api/diagnostics_channel.md
View File

@ -635,8 +635,6 @@ added:
- v18.19.0
-->
> Stability: 1 - Experimental
* `subscribers` {Object} Set of [TracingChannel Channels][] subscribers
* `start` {Function} The [`start` event][] subscriber
* `end` {Function} The [`end` event][] subscriber
@ -704,8 +702,6 @@ added:
- v18.19.0
-->
> Stability: 1 - Experimental
* `subscribers` {Object} Set of [TracingChannel Channels][] subscribers
* `start` {Function} The [`start` event][] subscriber
* `end` {Function} The [`end` event][] subscriber
@ -775,8 +771,6 @@ added:
- v18.19.0
-->
> Stability: 1 - Experimental
* `fn` {Function} Function to wrap a trace around
* `context` {Object} Shared object to correlate events through
* `thisArg` {any} The receiver to be used for the function call
@ -826,8 +820,6 @@ added:
- v18.19.0
-->
> Stability: 1 - Experimental
* `fn` {Function} Promise-returning function to wrap a trace around
* `context` {Object} Shared object to correlate trace events through
* `thisArg` {any} The receiver to be used for the function call
@ -880,8 +872,6 @@ added:
- v18.19.0
-->
> Stability: 1 - Experimental
* `fn` {Function} callback using function to wrap a trace around
* `position` {number} Zero-indexed argument position of expected callback
(defaults to last argument if `undefined` is passed)
@ -985,8 +975,6 @@ added:
- v20.13.0
-->
> Stability: 1 - Experimental
* Returns: {boolean} `true` if any of the individual channels has a subscriber,
`false` if not.

4
doc/api/esm.md
View File

@ -275,8 +275,6 @@ changes:
description: Switch from Import Assertions to Import Attributes.
-->
> Stability: 2 - Stable
[Import attributes][Import Attributes MDN] are an inline syntax for module import
statements to pass on more information alongside the module specifier.
@ -640,8 +638,6 @@ changes:
description: JSON modules are no longer experimental.
-->
> Stability: 2 - Stable
JSON files can be referenced by `import`:
```js

4
doc/api/events.md
View File

@ -2444,8 +2444,6 @@ changes:
description: No longer behind `--experimental-global-customevent` CLI flag.
-->
> Stability: 2 - Stable
* Extends: {Event}
The `CustomEvent` object is an adaptation of the [`CustomEvent` Web API][].
@ -2465,8 +2463,6 @@ changes:
description: CustomEvent is now stable.
-->
> Stability: 2 - Stable
* Type: {any} Returns custom data passed when initializing.
Read-only.

78
doc/api/globals.md
View File

@ -31,6 +31,8 @@ changes:
description: No longer experimental.
-->
> Stability: 2 - Stable
<!-- type=global -->
A utility class used to signal cancelation in selected `Promise`-based APIs.
@ -230,6 +232,8 @@ If `abortSignal.aborted` is `true`, throws `abortSignal.reason`.
added: v18.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
See {Blob}.
@ -240,6 +244,8 @@ See {Blob}.
added: v0.1.103
-->
> Stability: 2 - Stable
<!-- type=global -->
* {Function}
@ -282,6 +288,8 @@ Global alias for [`buffer.atob()`][].
added: v18.0.0
-->
> Stability: 2 - Stable
See {BroadcastChannel}.
## `btoa(data)`
@ -300,6 +308,8 @@ Global alias for [`buffer.btoa()`][].
added: v0.9.1
-->
> Stability: 2 - Stable
<!--type=global-->
[`clearImmediate`][] is described in the [timers][] section.
@ -310,6 +320,8 @@ added: v0.9.1
added: v0.0.1
-->
> Stability: 2 - Stable
<!--type=global-->
[`clearInterval`][] is described in the [timers][] section.
@ -320,6 +332,8 @@ added: v0.0.1
added: v0.0.1
-->
> Stability: 2 - Stable
<!--type=global-->
[`clearTimeout`][] is described in the [timers][] section.
@ -330,6 +344,8 @@ added: v0.0.1
added: v23.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `CloseEvent` class. See [`CloseEvent`][] for more details.
@ -355,6 +371,8 @@ A browser-compatible implementation of [`CompressionStream`][].
added: v0.1.100
-->
> Stability: 2 - Stable
<!-- type=global -->
* {Object}
@ -388,7 +406,7 @@ changes:
description: No longer behind `--experimental-global-webcrypto` CLI flag.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
A browser-compatible implementation of {Crypto}. This global is available
only if the Node.js binary was compiled with including support for the
@ -409,7 +427,7 @@ changes:
description: No longer behind `--experimental-global-webcrypto` CLI flag.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
A browser-compatible implementation of the [Web Crypto API][].
@ -428,7 +446,7 @@ changes:
description: No longer behind `--experimental-global-webcrypto` CLI flag.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
A browser-compatible implementation of {CryptoKey}. This global is available
only if the Node.js binary was compiled with including support for the
@ -482,6 +500,8 @@ changes:
description: No longer experimental.
-->
> Stability: 2 - Stable
<!-- type=global -->
A browser-compatible implementation of the `Event` class. See
@ -510,6 +530,8 @@ changes:
description: No longer experimental.
-->
> Stability: 2 - Stable
<!-- type=global -->
A browser-compatible implementation of the `EventTarget` class. See
@ -545,6 +567,8 @@ A browser-compatible implementation of the [`fetch()`][] function.
added: v20.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
See {File}.
@ -630,6 +654,8 @@ of a server, it is shared across all users and requests.
added: v15.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `MessageChannel` class. See [`MessageChannel`][] for more details.
@ -640,6 +666,8 @@ The `MessageChannel` class. See [`MessageChannel`][] for more details.
added: v15.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `MessageEvent` class. See [`MessageEvent`][] for more details.
@ -650,6 +678,8 @@ The `MessageEvent` class. See [`MessageEvent`][] for more details.
added: v15.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `MessagePort` class. See [`MessagePort`][] for more details.
@ -772,6 +802,8 @@ console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21"
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details.
@ -782,6 +814,8 @@ The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details.
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceMark` class. See [`PerformanceMark`][] for more details.
@ -792,6 +826,8 @@ The `PerformanceMark` class. See [`PerformanceMark`][] for more details.
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details.
@ -802,6 +838,8 @@ The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details.
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details.
@ -812,6 +850,8 @@ The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details.
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceObserverEntryList` class. See
@ -823,6 +863,8 @@ The `PerformanceObserverEntryList` class. See
added: v19.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The `PerformanceResourceTiming` class. See [`PerformanceResourceTiming`][] for
@ -834,6 +876,8 @@ more details.
added: v16.0.0
-->
> Stability: 2 - Stable
The [`perf_hooks.performance`][] object.
## `process`
@ -842,6 +886,8 @@ The [`perf_hooks.performance`][] object.
added: v0.1.7
-->
> Stability: 2 - Stable
<!-- type=global -->
* {Object}
@ -854,6 +900,8 @@ The process object. See the [`process` object][] section.
added: v11.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
* `callback` {Function} Function to be queued.
@ -1022,6 +1070,8 @@ the currently running process, and is not shared between workers.
added: v0.9.1
-->
> Stability: 2 - Stable
<!-- type=global -->
[`setImmediate`][] is described in the [timers][] section.
@ -1032,6 +1082,8 @@ added: v0.9.1
added: v0.0.1
-->
> Stability: 2 - Stable
<!-- type=global -->
[`setInterval`][] is described in the [timers][] section.
@ -1042,6 +1094,8 @@ added: v0.0.1
added: v0.0.1
-->
> Stability: 2 - Stable
<!-- type=global -->
[`setTimeout`][] is described in the [timers][] section.
@ -1063,6 +1117,8 @@ A browser-compatible implementation of [`Storage`][]. Enable this API with the
added: v17.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG [`structuredClone`][] method.
@ -1079,7 +1135,7 @@ changes:
description: No longer behind `--experimental-global-webcrypto` CLI flag.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
A browser-compatible implementation of {SubtleCrypto}. This global is available
only if the Node.js binary was compiled with including support for the
@ -1091,6 +1147,8 @@ only if the Node.js binary was compiled with including support for the
added: v17.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG `DOMException` class. See [`DOMException`][] for more details.
@ -1101,6 +1159,8 @@ The WHATWG `DOMException` class. See [`DOMException`][] for more details.
added: v11.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section.
@ -1123,6 +1183,8 @@ A browser-compatible implementation of [`TextDecoderStream`][].
added: v11.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section.
@ -1169,6 +1231,8 @@ A browser-compatible implementation of [`TransformStreamDefaultController`][].
added: v10.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG `URL` class. See the [`URL`][] section.
@ -1179,6 +1243,8 @@ The WHATWG `URL` class. See the [`URL`][] section.
added: v10.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section.
@ -1189,6 +1255,8 @@ The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section.
added: v8.0.0
-->
> Stability: 2 - Stable
<!-- type=global -->
* {Object}
@ -1212,7 +1280,7 @@ changes:
description: No longer behind `--experimental-websocket` CLI flag.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
A browser-compatible implementation of [`WebSocket`][]. Disable this API
with the [`--no-experimental-websocket`][] CLI flag.

6
doc/api/module.md
View File

@ -1026,9 +1026,6 @@ changes:
description: Add support for import assertions.
-->
> Stability: 1.2 - Release candidate (asynchronous version)
> Stability: 1.1 - Active development (synchronous version)
* `specifier` {string}
* `context` {Object}
* `conditions` {string\[]} Export conditions of the relevant `package.json`
@ -1142,9 +1139,6 @@ changes:
its return.
-->
> Stability: 1.2 - Release candidate (asynchronous version)
> Stability: 1.1 - Active development (synchronous version)
* `url` {string} The URL returned by the `resolve` chain
* `context` {Object}
* `conditions` {string\[]} Export conditions of the relevant `package.json`

2
doc/api/permissions.md
View File

@ -38,7 +38,7 @@ changes:
description: This feature is no longer experimental.
-->
> Stability: 2 - Stable.
> Stability: 2 - Stable
The Node.js Permission Model is a mechanism for restricting access to specific
resources during execution.

2
doc/api/test.md
View File

@ -2240,8 +2240,6 @@ changes:
description: The Mock Timers is now stable.
-->
> Stability: 2 - Stable
Mocking timers is a technique commonly used in software testing to simulate and
control the behavior of timers, such as `setInterval` and `setTimeout`,
without actually waiting for the specified time intervals.

2
doc/api/typescript.md
View File

@ -55,8 +55,6 @@ To use TypeScript with full support for all TypeScript features, including
added: v22.6.0
-->
> Stability: 1.1 - Active development
By default Node.js will execute TypeScript files that contains only
erasable TypeScript syntax.
Node.js will replace TypeScript syntax with whitespace,

6
doc/api/url.md
View File

@ -1560,8 +1560,6 @@ changes:
description: The Legacy URL API is deprecated. Use the WHATWG URL API.
-->
> Stability: 3 - Legacy: Use the WHATWG URL API instead.
The legacy `urlObject` (`require('node:url').Url` or
`import { Url } from 'node:url'`) is
created and returned by the `url.parse()` function.
@ -1689,8 +1687,6 @@ changes:
times.
-->
> Stability: 3 - Legacy: Use the WHATWG URL API instead.
* `urlObject` {Object|string} A URL object (as returned by `url.parse()` or
constructed otherwise). If a string, it is converted to an object by passing
it to `url.parse()`.
@ -1851,8 +1847,6 @@ changes:
contains a hostname.
-->
> Stability: 3 - Legacy: Use the WHATWG URL API instead.
* `from` {string} The base URL to use if `to` is a relative URL.
* `to` {string} The target URL to resolve.

8
doc/api/zlib.md
View File

@ -733,8 +733,6 @@ streams:
#### Flush operations
> Stability: 1 - Experimental
The following values are valid flush operations for Zstd-based streams:
* `zlib.constants.ZSTD_e_continue` (default for all operations)
@ -743,8 +741,6 @@ The following values are valid flush operations for Zstd-based streams:
#### Compressor options
> Stability: 1 - Experimental
There are several options that can be set on Zstd encoders, affecting
compression efficiency and speed. Both the keys and the values can be accessed
as properties of the `zlib.constants` object.
@ -757,16 +753,12 @@ The most important options are:
#### Pledged Source Size
> Stability: 1 - Experimental
It's possible to specify the expected total size of the uncompressed input via
`opts.pledgedSrcSize`. If the size doesn't match at the end of the input,
compression will fail with the code `ZSTD_error_srcSize_wrong`.
#### Decompressor options
> Stability: 1 - Experimental
These advanced options are available for controlling decompression:
* `ZSTD_d_windowLogMax`

7
doc/api_assets/style.css
View File

@ -294,6 +294,10 @@ li.picker-header a span {
margin: 0 0 1rem;
padding: 1rem;
line-height: 1.5;
position: sticky;
top: 3rem;
z-index: 1;
}
.api_stability * {
@ -827,6 +831,9 @@ kbd {
position: relative;
top: 0;
}
.api_stability {
top: 0;
}
}
@media not screen, (max-height: 1000px) {

31
tools/doc/html.mjs
View File

@ -216,6 +216,22 @@ export function preprocessElements({ filename }) {
visit(tree, null, (node, index, parent) => {
if (node.type === 'heading') {
headingIndex = index;
if (heading) {
node.parentHeading = heading;
for (let d = heading.depth; d >= node.depth; d--) {
node.parentHeading = node.parentHeading.parentHeading;
}
if (heading.depth > 2 || node.depth > 2) {
const isNonWrapped = node.depth > 2; // For depth of 1 and 2, there's already a wrapper.
parent.children.splice(index++, 0, {
type: 'html',
value:
`</div>`.repeat(heading.depth - node.depth + isNonWrapped) +
(isNonWrapped ? '<div>' : ''),
});
}
}
heading = node;
} else if (node.type === 'code') {
if (!node.lang) {
@ -286,13 +302,20 @@ export function preprocessElements({ filename }) {
if (heading && isStabilityIndex) {
heading.stability = number;
for (let h = heading; h != null; h = h.parentHeading) {
if (!h.hasStabilityIndexElement) continue;
if (h.stability === number && h.explication === explication) {
throw new Error(`Duplicate stability index at ${filename}:${node.position.start.line}, it already inherits it from a parent heading ${filename}:${h.position.start.line}`);
} else break;
}
heading.hasStabilityIndexElement = true;
heading.explication = explication;
headingIndex = -1;
heading = null;
}
// Do not link to the section we are already in.
const noLinking = filename.includes('documentation') &&
heading !== null && heading.children[0].value === 'Stability index';
!heading.hasStabilityIndexElement && heading.children[0].value === 'Stability index';
// Collapse blockquote and paragraph into a single node
node.type = 'paragraph';
@ -316,6 +339,10 @@ export function preprocessElements({ filename }) {
node.children.push({ type: 'html', value: '</div>' });
}
}
// In case we've inserted/removed node(s) before the current one, we need
// to make sure we're not visiting the same node again or skipping one.
return [true, index + 1];
});
};
}