Commit 6f7de0b
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 <luigipinca@gmail.com>
Reviewed-By: Yuta Hiroto <hello@hiroppy.me>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Weijia Wang <starkwang@126.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>1 parent dd2fc90 commit 6f7de0b
1 file changed
Lines changed: 15 additions & 19 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -419,25 +419,20 @@ the future." | |||
| 419 | 419 | ||
| 420 | 420 | Node.js uses three Deprecation levels: | |
| 421 | 421 | ||
| 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. | ||
| 441 | 436 | Backward-incompatible changes including complete removal of such APIs may | |
| 442 | 437 | occur at any time. | |
| 443 | 438 | ||
@@ -884,6 +879,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` may help. | |||
| 884 | 879 | [TSC]: https://github.com/nodejs/TSC | |
| 885 | 880 | [_Deprecation_]: https://en.wikipedia.org/wiki/Deprecation | |
| 886 | 881 | [`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation | |
| 882 | + [`--throw-deprecation`]: doc/api/cli.md#--throw-deprecation | ||
| 887 | 883 | [`node-core-utils`]: https://github.com/nodejs/node-core-utils | |
| 888 | 884 | [backporting guide]: doc/guides/backporting-to-release-lines.md | |
| 889 | 885 | [contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines | |
0 commit comments