Skip to content

Commit

Permalink
doc: revise "Breaking Changes to Internal Elements"
Browse files Browse the repository at this point in the history
Revise the "Breaking Changes to Internal Elements" section of
COLLABORATOR_GUIDE.md. Simplify wording, shorten sentences, and remove
redundant material.

PR-URL: #25190
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
  • Loading branch information
Trott authored and MylesBorins committed May 16, 2019
1 parent 5d5ac23 commit 18e0a61
Showing 1 changed file with 7 additions and 14 deletions.
21 changes: 7 additions & 14 deletions COLLABORATOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,20 +269,13 @@ For more information, see [Deprecations](#deprecations).

#### Breaking Changes to Internal Elements

Breaking changes to internal elements are permitted in semver-patch or
semver-minor commits but Collaborators should take significant care when
making and reviewing such changes. Before landing such commits, an effort
must be made to determine the potential impact of the change in the ecosystem
by analyzing current use and by validating such changes through ecosystem
testing using the [Canary in the Goldmine](https://github.com/nodejs/citgm)
tool. If a change cannot be made without ecosystem breakage, then TSC review is
required before landing the change as anything less than semver-major.

If a determination is made that a particular internal API (for instance, an
underscore `_` prefixed property) is sufficiently relied upon by the ecosystem
such that any changes may break user code, then serious consideration should be
given to providing an alternative Public API for that functionality before any
breaking changes are made.
Breaking changes to internal elements may occur in semver-patch or semver-minor
commits. Collaborators should take significant care when making and reviewing
such changes. An effort must be made to determine the potential impact of the
change in the ecosystem. Use
[Canary in the Goldmine](https://github.com/nodejs/citgm) to test such changes.
If a change will cause ecosystem breakage, then it is semver-major. Consider
providing a Public API in such cases.

#### When Breaking Changes Actually Break Things

Expand Down

0 comments on commit 18e0a61

Please sign in to comment.