From c276851b2f0074a7402115d5336737f84726fa9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=BA=D0=BE=D0=B2=D0=BE=D1=80=D0=BE=D0=B4=D0=B0=20?= =?UTF-8?q?=D0=9D=D0=B8=D0=BA=D0=B8=D1=82=D0=B0=20=D0=90=D0=BD=D0=B4=D1=80?= =?UTF-8?q?=D0=B5=D0=B5=D0=B2=D0=B8=D1=87?= Date: Mon, 29 Jan 2018 20:10:31 +0300 Subject: [PATCH 1/2] doc: add pending-deprecation to COLLABORATOR_GUIDE This is described as being a doc-only deprecation subset. Refs: https://github.com/nodejs/node/issues/18417 PR-URL: https://github.com/nodejs/node/pull/18433 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Luigi Pinca Reviewed-By: Daniel Bevenius Reviewed-By: Rich Trott --- COLLABORATOR_GUIDE.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 5a1d51dafe375c..e00437ee7cfe37 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -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 @@ -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 From 4efde4d0d4934dd8b47c11011e47eb27ad78a7ae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A1=D0=BA=D0=BE=D0=B2=D0=BE=D1=80=D0=BE=D0=B4=D0=B0=20?= =?UTF-8?q?=D0=9D=D0=B8=D0=BA=D0=B8=D1=82=D0=B0=20=D0=90=D0=BD=D0=B4=D1=80?= =?UTF-8?q?=D0=B5=D0=B5=D0=B2=D0=B8=D1=87?= Date: Mon, 29 Jan 2018 20:23:09 +0300 Subject: [PATCH 2/2] doc: add pending-deprecation to deprecations list This adds a mention of `--pending-deprecation` flag effect in the Deprecated APIs document, and explicitly labels deprecations that support it. Refs: https://github.com/nodejs/node/issues/18417 PR-URL: https://github.com/nodejs/node/pull/18433 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Luigi Pinca Reviewed-By: Daniel Bevenius Reviewed-By: Rich Trott --- doc/api/deprecations.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index e38c29949c4ced..de2f42cd0e63fd 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -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 @@ -66,7 +72,7 @@ be used. ### 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. @@ -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