Commit f182696
doc: document non-node_modules-only runtime deprecation
We already have this special kind of runtime deprecation for
Buffer constructors which does not fit into the original
description of runtiem deprecations. Document this kind of
deprecation separately.
PR-URL: #50748
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>1 parent c91b817 commit f182696
1 file changed
Lines changed: 15 additions & 7 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -10,10 +10,11 @@ Node.js APIs might be deprecated for any of the following reasons: | |||
| 10 | 10 | * An improved alternative API is available. | |
| 11 | 11 | * Breaking changes to the API are expected in a future major release. | |
| 12 | 12 | ||
| 13 | - Node.js uses three kinds of Deprecations: | ||
| 13 | + Node.js uses four kinds of deprecations: | ||
| 14 | 14 | ||
| 15 | 15 | * Documentation-only | |
| 16 | - * Runtime | ||
| 16 | + * Application (non-`node_modules` code only) | ||
| 17 | + * Runtime (all code) | ||
| 17 | 18 | * End-of-Life | |
| 18 | 19 | ||
| 19 | 20 | A Documentation-only deprecation is one that is expressed only within the | |
@@ -25,10 +26,17 @@ deprecations below. Documentation-only deprecations that support that flag | |||
| 25 | 26 | are explicitly labeled as such in the | |
| 26 | 27 | [list of Deprecated APIs](#list-of-deprecated-apis). | |
| 27 | 28 | ||
| 28 | - A Runtime deprecation will, by default, generate a process warning that will | ||
| 29 | - be printed to `stderr` the first time the deprecated API is used. When the | ||
| 30 | - [`--throw-deprecation`][] command-line flag is used, a Runtime deprecation will | ||
| 31 | - cause an error to be thrown. | ||
| 29 | + An Application deprecation for only non-`node_modules` code will, by default, | ||
| 30 | + generate a process warning that will be printed to `stderr` the first time | ||
| 31 | + the deprecated API is used in code that's not loaded from `node_modules`. | ||
| 32 | + When the [`--throw-deprecation`][] command-line flag is used, a Runtime | ||
| 33 | + deprecation will cause an error to be thrown. When | ||
| 34 | + [`--pending-deprecation`][] is used, warnings will also be emitted for | ||
| 35 | + code loaded from `node_modules`. | ||
| 36 | + | ||
| 37 | + A runtime deprecation for all code is similar to the runtime deprecation | ||
| 38 | + for non-`node_modules` code, except that it also emits a warning for | ||
| 39 | + code loaded from `node_modules`. | ||
| 32 | 40 | ||
| 33 | 41 | An End-of-Life deprecation is used when functionality is or will soon be removed | |
| 34 | 42 | from Node.js. | |
@@ -140,7 +148,7 @@ changes: | |||
| 140 | 148 | description: Documentation-only deprecation. | |
| 141 | 149 | --> | |
| 142 | 150 | ||
| 143 | - Type: Runtime (supports [`--pending-deprecation`][]) | ||
| 151 | + Type: Application (non-`node_modules` code only) | ||
| 144 | 152 | ||
| 145 | 153 | The `Buffer()` function and `new Buffer()` constructor are deprecated due to | |
| 146 | 154 | API usability issues that can lead to accidental security issues. | |
0 commit comments