summaryrefslogtreecommitdiff
path: root/COLLABORATOR_GUIDE.md
diff options
context:
space:
mode:
authorRich Trott <rtrott@gmail.com>2018-12-18 14:54:00 -0800
committerRich Trott <rtrott@gmail.com>2018-12-21 09:56:20 -0800
commit966a2df0f620cfe59e6ce2b161ff8bf7446b46ee (patch)
treef65b8076c70624f766bbe48c7f4182b1c2c472dd /COLLABORATOR_GUIDE.md
parent845fdd02f40b529a47c51f88b723ebccbff9f095 (diff)
downloadandroid-node-v8-966a2df0f620cfe59e6ce2b161ff8bf7446b46ee.tar.gz
android-node-v8-966a2df0f620cfe59e6ce2b161ff8bf7446b46ee.tar.bz2
android-node-v8-966a2df0f620cfe59e6ce2b161ff8bf7446b46ee.zip
doc: revise "Breaking Changes and Deprecations"
Revise the "Breaking Changes and Deprecations" section of the Collaborator Guide. Simplify the text. Remove redundant text. The "Deprecations" section is thorough and linked to from this section. PR-URL: https://github.com/nodejs/node/pull/25116 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Diffstat (limited to 'COLLABORATOR_GUIDE.md')
-rw-r--r--COLLABORATOR_GUIDE.md29
1 files changed, 6 insertions, 23 deletions
diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md
index 2d45f25c6a..71cb741e98 100644
--- a/COLLABORATOR_GUIDE.md
+++ b/COLLABORATOR_GUIDE.md
@@ -256,31 +256,14 @@ Examples of breaking changes include:
#### Breaking Changes and Deprecations
-With a few exceptions outlined below, when backward-incompatible changes to a
-*Public* API are necessary, the existing API *must* be deprecated *first* and
-the new API either introduced in parallel or added after the next major Node.js
-version following the deprecation as a replacement for the deprecated API. In
-other words, as a general rule, existing *Public* APIs *must not* change (in a
-backward-incompatible way) without a deprecation.
+Existing stable public APIs that change in a backward-incompatible way must
+undergo deprecation. The exceptions to this rule are:
-Exceptions to this rule may be made in the following cases:
-
-* Adding or removing errors thrown or reported by a Public API;
+* Adding or removing errors thrown or reported by a public API;
* Changing error messages for errors without error code;
-* Altering the timing and non-internal side effects of the Public API.
-
-Such changes *must* be handled as semver-major changes but MAY be landed
-without a [Deprecation cycle](#deprecation-cycle).
-
-Note that errors thrown, along with behaviors and APIs implemented by
-dependencies of Node.js (e.g. those originating from V8) are generally not
-under the control of Node.js and therefore *are not directly subject to this
-policy*. However, care should still be taken when landing updates to
-dependencies when it is known or expected that breaking changes to error
-handling may have been made. Additional CI testing may be required.
-
-From time-to-time, in particularly exceptional cases, the TSC may be asked to
-consider and approve additional exceptions to this rule.
+* Altering the timing and non-internal side effects of the public API;
+* Changes to errors thrown by dependencies of Node.js, such as V8;
+* One-time exceptions granted by the TSC.
For more information, see [Deprecations](#deprecations).