Skip to content

Commit 5149e18

Browse files
jasnelltargos
authored andcommitted
doc: deprecation clarifications
PR-URL: #19522 Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]>
1 parent 152a86c commit 5149e18

File tree

1 file changed

+11
-9
lines changed

1 file changed

+11
-9
lines changed

COLLABORATOR_GUIDE.md

+11-9
Original file line numberDiff line numberDiff line change
@@ -408,10 +408,8 @@ recommended but not required.
408408

409409
### Deprecations
410410

411-
_Deprecation_ refers to the identification of Public APIs that should no longer
412-
be used and that may be removed or modified in backward-incompatible ways in
413-
a future major release of Node.js. Deprecation may be used with internal APIs if
414-
there is expected impact on the user community.
411+
__Deprecation__ refers to the identification of Public APIs that should no
412+
longer be used.
415413

416414
Node.js uses three Deprecation levels:
417415

@@ -420,9 +418,9 @@ Node.js uses three Deprecation levels:
420418
notice indicating the deprecated status is added to the API documentation
421419
but no functional changes are implemented in the code. There will be no
422420
runtime deprecation warnings emitted for such deprecations by default.
423-
Documentation-only deprecations may trigger a runtime warning when launched
424-
with [`--pending-deprecation`][] flag (or its alternative,
425-
`NODE_PENDING_DEPRECATION=1` environment variable).
421+
Documentation-only deprecations may trigger a runtime warning when Node.js
422+
is started with the [`--pending-deprecation`][] flag or the
423+
`NODE_PENDING_DEPRECATION=1` environment variable is set.
426424

427425
* *Runtime Deprecation* refers to the use of process warnings emitted at
428426
runtime the first time that a deprecated API is used. A command-line
@@ -432,7 +430,9 @@ Node.js uses three Deprecation levels:
432430
deprecated status.
433431

434432
* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
435-
are ready to be removed from Node.js entirely.
433+
are no longer subject to the semantic versioning rules used by the project.
434+
Backward-incompatible changes including complete removal of such APIs may occur
435+
at any time.
436436

437437
Documentation-Only Deprecations may be handled as semver-minor or semver-major
438438
changes. Such deprecations have no impact on the successful operation of running
@@ -457,7 +457,9 @@ Deprecations may land in a Node.js minor release but must not be upgraded to
457457
a Runtime Deprecation until the next major release.)
458458

459459
No API can be moved to End-of-life without first having gone through a
460-
Runtime Deprecation cycle.
460+
Runtime Deprecation cycle. However, there is no requirement that deprecated
461+
code must progress ultimately to *End-of-Life*. Documentation-only and runtime
462+
deprecations may remain indefinitely.
461463

462464
A best effort will be made to communicate pending deprecations and associated
463465
mitigations with the ecosystem as soon as possible (preferably before the pull

0 commit comments

Comments
 (0)