From 109af1588d6dd03667de704ead9ab0e7a2a62637 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Fri, 9 Feb 2018 17:45:23 +0100 Subject: [PATCH 1/2] doc: more stability guarantees in deprecation policy Since this has come up a couple of times in previous, this codifies some expectations of stability that ecosystem developers have. --- COLLABORATOR_GUIDE.md | 33 +++++++++++++++++++++++++++------ 1 file changed, 27 insertions(+), 6 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 95ef0653552c1e..0b5b28bc537e1a 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -364,13 +364,13 @@ there is expected impact on the user community. Node.js uses three Deprecation levels: -* *Documentation-Only Deprecation* refers to elements of the Public API that are - 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 by default. +* *Documentation-Only Deprecation* refers to elements of the Public API that + should be avoided by developers. An explicit notice indicating the deprecation + status is added to the API documentation but no functional changes are + implemented in the code. + There will be no warnings emitted for such deprecations at runtime by default. Documentation-only deprecations may trigger a runtime warning when launched - with [`--pending-deprecation`][] flag (or its alternative, + with [`--pending-deprecation`][] flag (or its alternative, the `NODE_PENDING_DEPRECATION=1` environment variable). * *Runtime Deprecation* refers to the use of process warnings emitted at @@ -391,6 +391,27 @@ Runtime Deprecations and End-of-life APIs (internal or public) must be handled as semver-major changes unless there is TSC consensus to land the deprecation as a semver-minor. +Possible reasons for Runtime deprecations can be: + +* Node.js will no longer be able to support the API, for example if required + code is being removed in an upstream project. + +* The API is too hard or impossible to use correctly, increasing the risk of + undetected bugs or security issues in existing code. + +* Breaking the API makes way for simplification of its implementation that is + significant enough to make maintainability of Node.js easier, or enables + implementation of features that would otherwise be impossible. + +In addition, a Documentation-Only deprecation may be issued if it is desirable +to recommend a single canonical way out of multiple different ones +which achieve a particular goal with Node.js. + +In particular, a Runtime deprecation should *not* be added to an API that +that requires only trivial maintenance, or only because it has +never been documented or has only accidentally been exposed and there is +usage of said API in existing ecosystem code. + All Documentation-Only and Runtime deprecations will be assigned a unique identifier that can be used to persistently refer to the deprecation in documentation, emitted process warnings, or errors thrown. Documentation for From d5d524ee7d1841b721f5ad3adf9241dcfd646a77 Mon Sep 17 00:00:00 2001 From: Anna Henningsen Date: Tue, 13 Feb 2018 20:41:18 +0100 Subject: [PATCH 2/2] [squash] nits/suggestions --- COLLABORATOR_GUIDE.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 0b5b28bc537e1a..53cfb1732cc0e0 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -393,11 +393,11 @@ deprecation as a semver-minor. Possible reasons for Runtime deprecations can be: -* Node.js will no longer be able to support the API, for example if required +* Node.js will no longer be able to support the API, for example, if required code is being removed in an upstream project. -* The API is too hard or impossible to use correctly, increasing the risk of - undetected bugs or security issues in existing code. +* The API is deemed too hard or impossible to use correctly, increasing the + risk of undetected bugs or security issues in existing code. * Breaking the API makes way for simplification of its implementation that is significant enough to make maintainability of Node.js easier, or enables @@ -407,10 +407,11 @@ In addition, a Documentation-Only deprecation may be issued if it is desirable to recommend a single canonical way out of multiple different ones which achieve a particular goal with Node.js. -In particular, a Runtime deprecation should *not* be added to an API that -that requires only trivial maintenance, or only because it has -never been documented or has only accidentally been exposed and there is -usage of said API in existing ecosystem code. +A Runtime deprecation should not be added to an API that +requires only trivial maintenance. A Runtime deprecation should +not be added simply because an API has never been documented +(or has only accidentally been exposed) if there is significant usage +of the API in the ecosystem. All Documentation-Only and Runtime deprecations will be assigned a unique identifier that can be used to persistently refer to the deprecation in