doc: improve doc on unintended breaking changes

Improve the material in the Collaborator Guide on unintended breaking
changes.

PR-URL: https://github.com/nodejs/node/pull/25887
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
This commit is contained in:
Rich Trott 2019-02-02 00:05:16 -08:00
parent f395a4a401
commit 3fe9267592

View File

@ -17,7 +17,7 @@
- [Breaking Changes](#breaking-changes) - [Breaking Changes](#breaking-changes)
- [Breaking Changes and Deprecations](#breaking-changes-and-deprecations) - [Breaking Changes and Deprecations](#breaking-changes-and-deprecations)
- [Breaking Changes to Internal Elements](#breaking-changes-to-internal-elements) - [Breaking Changes to Internal Elements](#breaking-changes-to-internal-elements)
- [When Breaking Changes Actually Break Things](#when-breaking-changes-actually-break-things) - [Unintended Breaking Changes](#unintended-breaking-changes)
- [Reverting commits](#reverting-commits) - [Reverting commits](#reverting-commits)
- [Introducing New Modules](#introducing-new-modules) - [Introducing New Modules](#introducing-new-modules)
- [Additions to N-API](#additions-to-n-api) - [Additions to N-API](#additions-to-n-api)
@ -276,14 +276,12 @@ an effort to determine the potential impact of the change in the ecosystem. Use
If a change will cause ecosystem breakage, then it is semver-major. Consider If a change will cause ecosystem breakage, then it is semver-major. Consider
providing a Public API in such cases. providing a Public API in such cases.
#### When Breaking Changes Actually Break Things #### Unintended Breaking Changes
When any changes are landed on the master branch and it is determined that the Sometimes, a change intended to be non-breaking turns out to be a breaking
changes *do* break existing code, a decision may be made to revert those change. If such a change lands on the master branch, a Collaborator may revert
changes either temporarily or permanently. However, the decision to revert or it. As an alternative to reverting, the TSC may apply the semver-major label
not can often be based on many complex factors that are not easily codified. It after-the-fact.
is also possible that the breaking commit can be labeled retroactively as a
semver-major change that will not be backported to Current or LTS branches.
##### Reverting commits ##### Reverting commits