Skip to content

doc: revise "Breaking Changes to Internal Elements" #25190

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.

Sign up for GitHub

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

Closed
Trott wants to merge 2 commits into from
Closed

doc: revise "Breaking Changes to Internal Elements" #25190

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4e3b7c0
doc: revise "Breaking Changes to Internal Elements"
Trott Dec 23, 2018
5b10190
fixup! doc: revise "Breaking Changes to Internal Elements"
Trott Dec 25, 2018
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
20 changes: 6 additions & 14 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,20 +269,12 @@ 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 be semver-patch or semver-minor.
Copy link
Copy Markdown
Contributor

@cjihrig cjihrig Dec 23, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this sentence makes more sense if you switch the "may be semver-patch or semver-minor." back to "are permitted in semver-patch or semver-minor commits."

Copy link
Copy Markdown
Member Author

@Trott Trott Dec 25, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might be just going overboard with trying to avoid passive voice, but how about this?:

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
⚡