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 1 commit
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
33 changes: 14 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
API documentation but no functional changes are implemented in the code. By
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API API

default there will be no deprecation warnings emitted for such deprecations at
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is being trimmed, maybe drop the first occurrence deprecation?

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. A command-line switch can be used to escalate such
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we link to/specify the switch?

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