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: improve --pending-deprecation documentation #18433

Merged
merged 2 commits into from
Jan 30, 2018
Merged

doc: improve --pending-deprecation documentation #18433

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c276851
doc: add pending-deprecation to COLLABORATOR_GUIDE
ChALkeR Jan 29, 2018
4efde4d
doc: add pending-deprecation to deprecations list
ChALkeR Jan 29, 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
6 changes: 5 additions & 1 deletion COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -368,7 +368,10 @@ Node.js uses three Deprecation levels:
being staged for deprecation in a future Node.js major release. An explicit
notice indicating the deprecated status is added to the API documentation
but no functional changes are implemented in the code. There will be no
runtime deprecation warnings emitted for such deprecations.
runtime deprecation warnings emitted for such deprecations by default.
Documentation-only deprecations may trigger a runtime warning when launched
with [`--pending-deprecation`][] flag (or its alternative,
`NODE_PENDING_DEPRECATION=1` environment variable).

* *Runtime Deprecation* refers to the use of process warnings emitted at
runtime the first time that a deprecated API is used. A command-line
Expand Down Expand Up @@ -744,6 +747,7 @@ LTS working group and the Release team.
[backporting guide]: doc/guides/backporting-to-release-lines.md
[Stability Index]: doc/api/documentation.md#stability-index
[Enhancement Proposal]: https://github.com/nodejs/node-eps
[`--pending-deprecation`]: doc/api/cli.md#--pending-deprecation
[git-username]: https://help.github.com/articles/setting-your-username-in-git/
[`node-core-utils`]: https://github.com/nodejs/node-core-utils
[TSC]: https://github.com/nodejs/TSC
9 changes: 8 additions & 1 deletion doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ Node.js utilizes three kinds of Deprecations:

A Documentation-only deprecation is one that is expressed only within the
Node.js API docs. These generate no side-effects while running Node.js.
Some Documentation-only deprecations trigger a runtime warning when launched
with [`--pending-deprecation`][] flag (or its alternative,
`NODE_PENDING_DEPRECATION=1` environment variable), similarly to Runtime
deprecations below. Documentation-only deprecations that support that flag
are explicitly labeled as such in the
[list of Deprecated APIs](#deprecations_list_of_deprecated_apis).

A Runtime deprecation will, by default, generate a process warning that will
be printed to `stderr` the first time the deprecated API is used. When the
Expand Down Expand Up @@ -66,7 +72,7 @@ be used.
<a id="DEP0005"></a>
### DEP0005: Buffer() constructor

Type: Documentation-only
Type: Documentation-only (supports [`--pending-deprecation`][])

The `Buffer()` function and `new Buffer()` constructor are deprecated due to
API usability issues that can potentially lead to accidental security issues.
Expand Down Expand Up @@ -818,6 +824,7 @@ a future version at which point only authentication tag lengths of 128, 120,
is not included in this list will be considered invalid in compliance with
[NIST SP 800-38D][].

[`--pending-deprecation`]: cli.html#cli_pending_deprecation
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
[`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer
Expand Down