Commit 0b96ece
committed
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 8d3ea97 commit 0b96ece
1 file changed
Lines changed: 9 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -387,6 +387,12 @@ undergo deprecation. The exceptions to this rule are: | |||
| 387 | 387 | * Changes to errors thrown by dependencies of Node.js, such as V8. | |
| 388 | 388 | * One-time exceptions granted by the TSC. | |
| 389 | 389 | ||
| 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 | + | ||
| 390 | 396 | For more information, see [Deprecations](#deprecations). | |
| 391 | 397 | ||
| 392 | 398 | #### Breaking changes to internal elements | |
@@ -526,8 +532,8 @@ the three Deprecation levels. Documentation-Only Deprecations can land in a | |||
| 526 | 532 | minor release. They can not change to a Runtime Deprecation until the next major | |
| 527 | 533 | release. | |
| 528 | 534 | ||
| 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. | ||
| 531 | 537 | Documentation-Only and Runtime Deprecations can remain in place for an unlimited | |
| 532 | 538 | duration. | |
| 533 | 539 | ||
@@ -1059,6 +1065,7 @@ need to be attached anymore, as only important bugfixes will be included. | |||
| 1059 | 1065 | [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues | |
| 1060 | 1066 | [ppc]: https://github.com/orgs/nodejs/teams/platform-ppc | |
| 1061 | 1067 | [s390]: https://github.com/orgs/nodejs/teams/platform-s390 | |
| 1068 | + [semantic versioning]: https://semver.org/ | ||
| 1062 | 1069 | [smartos]: https://github.com/orgs/nodejs/teams/platform-smartos | |
| 1063 | 1070 | [unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 | |
| 1064 | 1071 | [windows]: https://github.com/orgs/nodejs/teams/platform-windows | |
0 commit comments