Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: revise "Breaking Changes and Deprecations" #25116

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 6 additions & 23 deletions COLLABORATOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down