diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 2d45f25c6ab219..71cb741e989367 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).