Skip to content

Commit 5e44768

Browse files
Trottrvagg
authored andcommitted
doc: revise deprecation level explanations in Collaborator Guide
Revise deprecation level explanations for scanability and ease of understanding. PR-URL: #26197 Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Yuta Hiroto <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 108c698 commit 5e44768

File tree

1 file changed

+19
-18
lines changed

1 file changed

+19
-18
lines changed

COLLABORATOR_GUIDE.md

+19-18
Original file line numberDiff line numberDiff line change
@@ -319,24 +319,25 @@ guide](https://github.com/nodejs/node/blob/master/doc/guides/adding-new-napi-api
319319

320320
### Deprecations
321321

322-
Node.js uses three [Deprecation][] levels:
323-
324-
* *Documentation-Only Deprecation*: A deprecation notice is added to the API
325-
documentation but no functional changes are implemented in the code. By
326-
default, there will be no warnings emitted for such deprecations at
327-
runtime. Documentation-only deprecations may trigger a runtime warning when
328-
Node.js is started with the [`--pending-deprecation`][] flag or the
329-
`NODE_PENDING_DEPRECATION=1` environment variable is set.
330-
331-
* *Runtime Deprecation*: A warning is emitted at runtime the first time that a
332-
deprecated API is used. The [`--throw-deprecation`][] flag can be used to
333-
escalate such warnings into runtime errors that will cause the Node.js process
334-
to exit. As with Documentation-Only Deprecation, the documentation for the API
335-
must be updated to clearly indicate the deprecated status.
336-
337-
* *End-of-life*: The API is no longer subject to the semantic versioning rules.
338-
Backward-incompatible changes including complete removal of such APIs may
339-
occur at any time.
322+
Node.js uses three [Deprecation][] levels. For all deprecated APIs, the API
323+
documentation must state the deprecation status.
324+
325+
* Documentation-Only Deprecation
326+
* A deprecation notice appears in the API documentation.
327+
* There are no functional changes.
328+
* By default, there will be no warnings emitted for such deprecations at
329+
runtime.
330+
* May cause a runtime warning with the [`--pending-deprecation`][] flag or
331+
`NODE_PENDING_DEPRECATION` environment variable.
332+
333+
* Runtime Deprecation
334+
* Emits a warning at runtime on first use of the deprecated API.
335+
* If used with the [`--throw-deprecation`][] flag, will throw a runtime error.
336+
337+
* End-of-life
338+
* The API is no longer subject to the semantic versioning rules.
339+
* Backward-incompatible changes including complete removal of such APIs may
340+
occur at any time.
340341

341342
Documentation-Only Deprecations may be handled as semver-minor or semver-major
342343
changes. Such deprecations have no impact on the successful operation of running

0 commit comments

Comments
 (0)