Skip to content

Commit 6f7de0b

Browse files
Trotttargos
authored andcommitted
doc: trim deprecation level definition text
Provide more concise explanations of the deprecation levels in COLLABORATOR_GUIDE.md. PR-URL: #21241 Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Yuta Hiroto <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Tiancheng "Timothy" Gu <[email protected]> Reviewed-By: Ujjwal Sharma <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]> Reviewed-By: Weijia Wang <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]>
1 parent dd2fc90 commit 6f7de0b

File tree

1 file changed

+15
-19
lines changed

1 file changed

+15
-19
lines changed

COLLABORATOR_GUIDE.md

+15-19
Original file line numberDiff line numberDiff line change
@@ -419,25 +419,20 @@ the future."
419419

420420
Node.js uses three Deprecation levels:
421421

422-
* *Documentation-Only Deprecation* refers to elements of the Public API that
423-
should be avoided by developers and that might be staged for a runtime
424-
deprecation in a future Node.js major release. An explicit notice indicating
425-
the deprecation status is added to the API documentation but no functional
426-
changes are implemented in the code. By default there will be no deprecation
427-
warnings emitted for such deprecations at runtime. Documentation-only
428-
deprecations may trigger a runtime warning when Node.js is started with the
429-
[`--pending-deprecation`][] flag or the `NODE_PENDING_DEPRECATION=1`
430-
environment variable is set.
431-
432-
* *Runtime Deprecation* refers to the use of process warnings emitted at
433-
runtime the first time that a deprecated API is used. A command-line
434-
switch can be used to escalate such warnings into runtime errors that will
435-
cause the Node.js process to exit. As with Documentation-Only Deprecation,
436-
the documentation for the API must be updated to clearly indicate the
437-
deprecated status.
438-
439-
* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
440-
are no longer subject to the semantic versioning rules used by the project.
422+
* *Documentation-Only Deprecation*: A deprecation notice is added to the API
423+
documentation but no functional changes are implemented in the code. By
424+
default, there will be no warnings emitted for such deprecations at
425+
runtime. Documentation-only deprecations may trigger a runtime warning when
426+
Node.js is started with the [`--pending-deprecation`][] flag or the
427+
`NODE_PENDING_DEPRECATION=1` environment variable is set.
428+
429+
* *Runtime Deprecation*: A warning is emitted at runtime the first time that a
430+
deprecated API is used. The [`--throw-deprecation`][] flag can be used to
431+
escalate such warnings into runtime errors that will cause the Node.js process
432+
to exit. As with Documentation-Only Deprecation, the documentation for the API
433+
must be updated to clearly indicate the deprecated status.
434+
435+
* *End-of-life*: The API is no longer subject to the semantic versioning rules.
441436
Backward-incompatible changes including complete removal of such APIs may
442437
occur at any time.
443438

@@ -884,6 +879,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` may help.
884879
[TSC]: https://github.com/nodejs/TSC
885880
[_Deprecation_]: https://en.wikipedia.org/wiki/Deprecation
886881
[`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation
882+
[`--throw-deprecation`]: doc/api/cli.md#--throw-deprecation
887883
[`node-core-utils`]: https://github.com/nodejs/node-core-utils
888884
[backporting guide]: doc/guides/backporting-to-release-lines.md
889885
[contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines

0 commit comments

Comments
 (0)