From 536d2f4d724416868ac33c7c0b37304a3350e717 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 9 Jun 2018 20:16:37 -0700 Subject: [PATCH 1/4] doc: trim deprecation level definition text Provide more concise explanations of the deprecation levels in COLLABORATOR_GUIDE.md. --- COLLABORATOR_GUIDE.md | 33 ++++++++++++++------------------- 1 file changed, 14 insertions(+), 19 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index f5ffd35f04aa02..4785a97b41edcf 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -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 + 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*: 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 + 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. From 51a9ae14029e912a68f27e4bb92f5e62362f1490 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 10 Jun 2018 08:48:14 -0700 Subject: [PATCH 2/4] fixup! API API --- COLLABORATOR_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 4785a97b41edcf..0f40343eac1d40 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -420,7 +420,7 @@ the future." Node.js uses three Deprecation levels: * *Documentation-Only Deprecation*: A deprecation notice is added to the API - API documentation but no functional changes are implemented in the code. By + 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 From da00b3c9876649df8616acd38e79cd175272d800 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 10 Jun 2018 08:50:03 -0700 Subject: [PATCH 3/4] fixup! extra 'deprecation' removed, comma added --- COLLABORATOR_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 0f40343eac1d40..03ec0d10990434 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -421,7 +421,7 @@ Node.js uses three Deprecation levels: * *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 deprecation warnings emitted for such deprecations at + 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. From 889906e5f23f7e452ad3d1732f44a83d47402eb8 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 10 Jun 2018 14:12:51 -0700 Subject: [PATCH 4/4] squash! provide name and link for CLI flag --- COLLABORATOR_GUIDE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 03ec0d10990434..ea05a5ef0de77f 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -427,10 +427,10 @@ Node.js uses three Deprecation levels: `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 - 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. + 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 @@ -879,6 +879,7 @@ If you cannot find who to cc for a file, `git shortlog -n -s ` 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