Skip to content

Commit f92c61f

Browse files
authored
doc: clarify that features cannot be both experimental and deprecated
PR-URL: #62456 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
1 parent 60f19bc commit f92c61f

File tree

1 file changed

+9
-2
lines changed

1 file changed

+9
-2
lines changed

doc/contributing/collaborator-guide.md

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -387,6 +387,12 @@ undergo deprecation. The exceptions to this rule are:
387387
* Changes to errors thrown by dependencies of Node.js, such as V8.
388388
* One-time exceptions granted by the TSC.
389389

390+
Experimental and undocumented APIs are not considered stable, therefore are
391+
typically removed without a deprecation cycle. However, if such API has gotten
392+
some non-trivial adoption in the ecosystem, it (or a subset of it) can undergo
393+
deprecation – at which point, changes to that API (or at least, its deprecated
394+
subset) should follow [semantic versioning][] rules.
395+
390396
For more information, see [Deprecations](#deprecations).
391397

392398
#### Breaking changes to internal elements
@@ -526,8 +532,8 @@ the three Deprecation levels. Documentation-Only Deprecations can land in a
526532
minor release. They can not change to a Runtime Deprecation until the next major
527533
release.
528534

529-
No API can change to End-of-Life without going through a Runtime Deprecation
530-
cycle. There is no rule that deprecated code must progress to End-of-Life.
535+
No deprecated APIs can change to End-of-Life without going through a Runtime
536+
Deprecation cycle. There is no rule that deprecated code must progress to End-of-Life.
531537
Documentation-Only and Runtime Deprecations can remain in place for an unlimited
532538
duration.
533539

@@ -1059,6 +1065,7 @@ need to be attached anymore, as only important bugfixes will be included.
10591065
[node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues
10601066
[ppc]: https://github.com/orgs/nodejs/teams/platform-ppc
10611067
[s390]: https://github.com/orgs/nodejs/teams/platform-s390
1068+
[semantic versioning]: https://semver.org/
10621069
[smartos]: https://github.com/orgs/nodejs/teams/platform-smartos
10631070
[unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22
10641071
[windows]: https://github.com/orgs/nodejs/teams/platform-windows

0 commit comments

Comments
 (0)