Commit 5149e18
doc: deprecation clarifications
PR-URL: #19522
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>1 parent 152a86c commit 5149e18
1 file changed
Lines changed: 11 additions & 9 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -408,10 +408,8 @@ recommended but not required. | |||
| 408 | 408 | ||
| 409 | 409 | ### Deprecations | |
| 410 | 410 | ||
| 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. | ||
| 415 | 413 | ||
| 416 | 414 | Node.js uses three Deprecation levels: | |
| 417 | 415 | ||
@@ -420,9 +418,9 @@ Node.js uses three Deprecation levels: | |||
| 420 | 418 | notice indicating the deprecated status is added to the API documentation | |
| 421 | 419 | but no functional changes are implemented in the code. There will be no | |
| 422 | 420 | 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. | ||
| 426 | 424 | ||
| 427 | 425 | * *Runtime Deprecation* refers to the use of process warnings emitted at | |
| 428 | 426 | runtime the first time that a deprecated API is used. A command-line | |
@@ -432,7 +430,9 @@ Node.js uses three Deprecation levels: | |||
| 432 | 430 | deprecated status. | |
| 433 | 431 | ||
| 434 | 432 | * *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. | ||
| 436 | 436 | ||
| 437 | 437 | Documentation-Only Deprecations may be handled as semver-minor or semver-major | |
| 438 | 438 | 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 | |||
| 457 | 457 | a Runtime Deprecation until the next major release.) | |
| 458 | 458 | ||
| 459 | 459 | 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. | ||
| 461 | 463 | ||
| 462 | 464 | A best effort will be made to communicate pending deprecations and associated | |
| 463 | 465 | mitigations with the ecosystem as soon as possible (preferably before the pull | |
0 commit comments