Commit 5e44768
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 <riclau@uk.ibm.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Yuta Hiroto <hello@hiroppy.me>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent 108c698 commit 5e44768
1 file changed
Lines changed: 19 additions & 18 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -319,24 +319,25 @@ guide](https://github.com/nodejs/node/blob/master/doc/guides/adding-new-napi-api | |||
| 319 | 319 | ||
| 320 | 320 | ### Deprecations | |
| 321 | 321 | ||
| 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. | ||
| 340 | 341 | ||
| 341 | 342 | Documentation-Only Deprecations may be handled as semver-minor or semver-major | |
| 342 | 343 | changes. Such deprecations have no impact on the successful operation of running | |
0 commit comments