From 11c3a41304524597974a4d597a4fd4382f807f9a Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 21 Mar 2018 12:42:25 -0700 Subject: [PATCH 1/3] doc: deprecation clarifications --- COLLABORATOR_GUIDE.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 941694ced34d1c..934d275f0d663f 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -403,10 +403,11 @@ recommended but not required. ### Deprecations -_Deprecation_ refers to the identification of Public APIs that should no longer -be used and that may be removed or modified in backward-incompatible ways in -a future major release of Node.js. Deprecation may be used with internal APIs if -there is expected impact on the user community. +__Deprecation__ refers to the identification of Public APIs that should no +longer be used. + +Once specific bits of code are marked as being Deprecated, they are no longer +covered by the typical current or Long Term Support policies. Node.js uses three Deprecation levels: @@ -415,9 +416,9 @@ Node.js uses three Deprecation levels: 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 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). + Documentation-only deprecations may trigger an opt-in only runtime warning + when Node.js is launched with the [`--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 @@ -427,7 +428,9 @@ Node.js uses three Deprecation levels: deprecated status. * *End-of-life* refers to APIs that have gone through Runtime Deprecation and - are ready to be removed from Node.js entirely. + are no longer subject to the semantic-versioning and support policies used by + the project. Backward-incompatible changes or even complete removal of such + code may occur at any time. Documentation-Only Deprecations may be handled as semver-minor or semver-major changes. Such deprecations have no impact on the successful operation of running @@ -452,7 +455,10 @@ Deprecations may land in a Node.js minor release but must not be upgraded to a Runtime Deprecation until the next major release.) No API can be moved to End-of-life without first having gone through a -Runtime Deprecation cycle. +Runtime Deprecation cycle. However, there is no requirement that deprecated +code must progress ultimately to *End-of-Life*. It is possible, and at times +preferable, for code that is documentation-only or runtime deprecated to +remain so indefinitely. A best effort will be made to communicate pending deprecations and associated mitigations with the ecosystem as soon as possible (preferably before the pull From cb84aaa73217565adfdd67f483f531b247207731 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Thu, 22 Mar 2018 13:46:17 -0700 Subject: [PATCH 2/3] [Squash] address feedback --- COLLABORATOR_GUIDE.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 934d275f0d663f..54720fa58fb399 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -406,8 +406,8 @@ recommended but not required. __Deprecation__ refers to the identification of Public APIs that should no longer be used. -Once specific bits of code are marked as being Deprecated, they are no longer -covered by the typical current or Long Term Support policies. +Once APIs are Deprecated, they are no longer covered by the current or +[Long Term Support][LTS] policies. Node.js uses three Deprecation levels: @@ -416,9 +416,9 @@ Node.js uses three Deprecation levels: 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 by default. - Documentation-only deprecations may trigger an opt-in only runtime warning - when Node.js is launched with the [`--pending-deprecation`][] flag (or its - alternative, `NODE_PENDING_DEPRECATION=1` environment variable). + Documentation-only deprecations may trigger an runtime warning when Node.js + is launched 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 @@ -428,9 +428,9 @@ Node.js uses three Deprecation levels: deprecated status. * *End-of-life* refers to APIs that have gone through Runtime Deprecation and - are no longer subject to the semantic-versioning and support policies used by - the project. Backward-incompatible changes or even complete removal of such - code may occur at any time. + are no longer subject to the semantic versioning and [support policies](LTS) + used by the project. Backward-incompatible changes including complete removal + of such APIs may occur at any time. Documentation-Only Deprecations may be handled as semver-minor or semver-major changes. Such deprecations have no impact on the successful operation of running @@ -456,9 +456,8 @@ a Runtime Deprecation until the next major release.) No API can be moved to End-of-life without first having gone through a Runtime Deprecation cycle. However, there is no requirement that deprecated -code must progress ultimately to *End-of-Life*. It is possible, and at times -preferable, for code that is documentation-only or runtime deprecated to -remain so indefinitely. +code must progress ultimately to *End-of-Life*. Documentation-only and runtime +deprecations may remain indefinitely. A best effort will be made to communicate pending deprecations and associated mitigations with the ecosystem as soon as possible (preferably before the pull @@ -838,3 +837,4 @@ LTS working group and the Release team. [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials ["Merge Pull Request"]: https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-github [flaky tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 +[LTS]: https://github.com/nodejs/Release From 4c9c2815520d8e09f241c537d11098422531e6b4 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sat, 24 Mar 2018 07:40:43 -0700 Subject: [PATCH 3/3] [Squash] nits --- COLLABORATOR_GUIDE.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 54720fa58fb399..512d98d2e8fe2f 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -406,9 +406,6 @@ recommended but not required. __Deprecation__ refers to the identification of Public APIs that should no longer be used. -Once APIs are Deprecated, they are no longer covered by the current or -[Long Term Support][LTS] policies. - Node.js uses three Deprecation levels: * *Documentation-Only Deprecation* refers to elements of the Public API that are @@ -416,8 +413,8 @@ Node.js uses three Deprecation levels: 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 by default. - Documentation-only deprecations may trigger an runtime warning when Node.js - is launched with the [`--pending-deprecation`][] flag, or the + 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 @@ -428,9 +425,9 @@ Node.js uses three Deprecation levels: deprecated status. * *End-of-life* refers to APIs that have gone through Runtime Deprecation and - are no longer subject to the semantic versioning and [support policies](LTS) - used by the project. Backward-incompatible changes including complete removal - of such APIs may occur at any time. + are no longer subject to the semantic versioning rules used by the project. + Backward-incompatible changes including complete removal of such APIs may occur + at any time. Documentation-Only Deprecations may be handled as semver-minor or semver-major changes. Such deprecations have no impact on the successful operation of running @@ -837,4 +834,3 @@ LTS working group and the Release team. [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials ["Merge Pull Request"]: https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-github [flaky tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 -[LTS]: https://github.com/nodejs/Release