From 4e3b7c06012e63834836eebc468cd63003bfaf76 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 22 Dec 2018 19:49:31 -0800 Subject: [PATCH 1/2] doc: revise "Breaking Changes to Internal Elements" Revise the "Breaking Changes to Internal Elements" section of COLLABORATOR_GUIDE.md. Simplify wording, shorten sentences, and remove redundant material. --- COLLABORATOR_GUIDE.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 71cb741e989367..374c19c430b221 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -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. +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 From 5b1019020793acdf6cedf9c6c53a59e2f33e3df5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 24 Dec 2018 22:12:58 -0800 Subject: [PATCH 2/2] fixup! doc: revise "Breaking Changes to Internal Elements" --- COLLABORATOR_GUIDE.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 374c19c430b221..c3805d4a2c05f9 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -269,12 +269,13 @@ For more information, see [Deprecations](#deprecations). #### Breaking Changes to Internal Elements -Breaking changes to internal elements may be semver-patch or semver-minor. -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. +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