1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: trim deprecation level definition text

Browse Source 
Provide more concise explanations of the deprecation levels in
COLLABORATOR_GUIDE.md.

PR-URL: https://github.com/nodejs/node/pull/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>
This commit is contained in:
Rich Trott 2018-06-09 20:16:37 -07:00
parent 0d79c84a83
commit 4c166935ae
1 changed files with 13 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
COLLABORATOR_GUIDE.md
View File

@ -419,25 +419,20 @@ the future."
Node.js uses three Deprecation levels: Node.js uses three Deprecation levels:
* *Documentation-Only Deprecation* refers to elements of the Public API that * *Documentation-Only Deprecation*: A deprecation notice is added to the API
should be avoided by developers and that might be staged for a runtime documentation but no functional changes are implemented in the code. By
deprecation in a future Node.js major release. An explicit notice indicating default, there will be no warnings emitted for such deprecations at
the deprecation status is added to the API documentation but no functional runtime. Documentation-only deprecations may trigger a runtime warning when
changes are implemented in the code. By default there will be no deprecation Node.js is started with the [`--pending-deprecation`][] flag or the
warnings emitted for such deprecations at runtime. Documentation-only `NODE_PENDING_DEPRECATION=1` environment variable is set.
deprecations may trigger a runtime warning when Node.js is started with the
[`--pending-deprecation`][] flag or the `NODE_PENDING_DEPRECATION=1`
environment variable is set.
* *Runtime Deprecation* refers to the use of process warnings emitted at * *Runtime Deprecation*: A warning is emitted at runtime the first time that a
runtime the first time that a deprecated API is used. A command-line deprecated API is used. The [`--throw-deprecation`][] flag can be used to
switch can be used to escalate such warnings into runtime errors that will escalate such warnings into runtime errors that will cause the Node.js process
cause the Node.js process to exit. As with Documentation-Only Deprecation, to exit. As with Documentation-Only Deprecation, the documentation for the API
the documentation for the API must be updated to clearly indicate the must be updated to clearly indicate the deprecated status.
deprecated status.
* *End-of-life* refers to APIs that have gone through Runtime Deprecation and * *End-of-life*: The API is no longer subject to the semantic versioning rules.
are no longer subject to the semantic versioning rules used by the project.
Backward-incompatible changes including complete removal of such APIs may Backward-incompatible changes including complete removal of such APIs may
occur at any time. occur at any time.
@ -884,6 +879,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` may help.
[TSC]: https://github.com/nodejs/TSC [TSC]: https://github.com/nodejs/TSC
[_Deprecation_]: https://en.wikipedia.org/wiki/Deprecation [_Deprecation_]: https://en.wikipedia.org/wiki/Deprecation
[`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation [`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation
[`--throw-deprecation`]: doc/api/cli.md#--throw-deprecation
[`node-core-utils`]: https://github.com/nodejs/node-core-utils [`node-core-utils`]: https://github.com/nodejs/node-core-utils
[backporting guide]: doc/guides/backporting-to-release-lines.md [backporting guide]: doc/guides/backporting-to-release-lines.md
[contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines [contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines