Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: trim deprecation level definition text #21241

Closed
wants to merge 4 commits into from
Closed

doc: trim deprecation level definition text #21241

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
536d2f4
doc: trim deprecation level definition text
Trott Jun 10, 2018
51a9ae1
fixup! API API
Trott Jun 10, 2018
da00b3c
fixup! extra 'deprecation' removed, comma added
Trott Jun 10, 2018
889906e
squash! provide name and link for CLI flag
Trott Jun 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 15 additions & 19 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,25 +419,20 @@ the future."

Node.js uses three Deprecation levels:

* *Documentation-Only Deprecation* refers to elements of the Public API that
should be avoided by developers and that might be staged for a runtime
deprecation in a future Node.js major release. An explicit notice indicating
the deprecation status is added to the API documentation but no functional
changes are implemented in the code. By default there will be no deprecation
warnings emitted for such deprecations at runtime. Documentation-only
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 the first time that a deprecated API is used. A command-line
switch can be used to escalate such warnings into runtime errors that will
cause the Node.js process to exit. As with Documentation-Only Deprecation,
the documentation for the API must be updated to clearly indicate the
deprecated status.

* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
are no longer subject to the semantic versioning rules used by the project.
* *Documentation-Only Deprecation*: A deprecation notice is added to the API
documentation but no functional changes are implemented in the code. By
default, there will be no warnings emitted for such deprecations at
runtime. Documentation-only 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*: A warning is emitted at runtime the first time that a
deprecated API is used. The [`--throw-deprecation`][] flag can be used to
escalate such warnings into runtime errors that will cause the Node.js process
to exit. As with Documentation-Only Deprecation, the documentation for the API
must be updated to clearly indicate the deprecated status.

* *End-of-life*: The API is no longer subject to the semantic versioning rules.
Backward-incompatible changes including complete removal of such APIs may
occur at any time.

Expand Down Expand Up @@ -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
[_Deprecation_]: https://en.wikipedia.org/wiki/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
[backporting guide]: doc/guides/backporting-to-release-lines.md
[contributing]: ./doc/guides/contributing/pull-requests.md#commit-message-guidelines
Expand Down