Skip to content

Commit 2cbc6bb

Browse files
committed
fixup! doc: clarify that features cannot be both experimental and deprecated
1 parent 44572ae commit 2cbc6bb

3 files changed

Lines changed: 10 additions & 8 deletions

File tree

doc/api/deprecations.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,6 @@ Node.js APIs might be deprecated for any of the following reasons:
1010
* An improved alternative API is available.
1111
* Breaking changes to the API are expected in a future major release.
1212

13-
Deprecated features are subject to [semantic versioning][] rules.
14-
1513
Node.js uses four kinds of deprecations:
1614

1715
* Documentation-only
@@ -4681,7 +4679,6 @@ deprecated and will throw an error in a future version.
46814679
[legacy URL API]: url.md#legacy-url-api
46824680
[legacy `urlObject`]: url.md#legacy-urlobject
46834681
[permission model]: permissions.md#permission-model
4684-
[semantic versioning]: https://semver.org/
46854682
[static methods of `crypto.Certificate()`]: crypto.md#class-certificate
46864683
[subpath exports]: packages.md#subpath-exports
46874684
[subpath imports]: packages.md#subpath-imports

doc/api/documentation.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,7 @@ The stability indexes are as follows:
4646
> we can know that this feature is ready to be marked as stable.
4747
>
4848
> Experimental features leave the experimental status typically either by
49-
> graduating to stable, or are removed without a deprecation cycle. In less
50-
> common cases, if the feature has gotten large adoption in the ecosystem,
51-
> they can also leave the experimental status by being deprecated.
49+
> graduating to stable, or are removed without a deprecation cycle.
5250
5351
<!-- separator -->
5452

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 should follow
394+
[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)