diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index 6f2e400d440181..99b3ec84b3b9e0 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -387,6 +387,12 @@ undergo deprecation. The exceptions to this rule are: * Changes to errors thrown by dependencies of Node.js, such as V8. * One-time exceptions granted by the TSC. +Experimental and undocumented APIs are not considered stable, therefore are +typically removed without a deprecation cycle. However, if such API has gotten +some non-trivial adoption in the ecosystem, it (or a subset of it) can undergo +deprecation – at which point, changes to that API (or at least, its deprecated +subset) should follow [semantic versioning][] rules. + For more information, see [Deprecations](#deprecations). #### Breaking changes to internal elements @@ -526,8 +532,8 @@ the three Deprecation levels. Documentation-Only Deprecations can land in a minor release. They can not change to a Runtime Deprecation until the next major release. -No API can change to End-of-Life without going through a Runtime Deprecation -cycle. There is no rule that deprecated code must progress to End-of-Life. +No deprecated APIs can change to End-of-Life without going through a Runtime +Deprecation cycle. There is no rule that deprecated code must progress to End-of-Life. Documentation-Only and Runtime Deprecations can remain in place for an unlimited duration. @@ -1059,6 +1065,7 @@ need to be attached anymore, as only important bugfixes will be included. [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues [ppc]: https://github.com/orgs/nodejs/teams/platform-ppc [s390]: https://github.com/orgs/nodejs/teams/platform-s390 +[semantic versioning]: https://semver.org/ [smartos]: https://github.com/orgs/nodejs/teams/platform-smartos [unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 [windows]: https://github.com/orgs/nodejs/teams/platform-windows