From 92cb53a888b9efdefa12a251ceda86fb3214a9df Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 27 Mar 2026 10:19:49 +0100 Subject: [PATCH 1/4] doc: clarify that features cannot be both experimental and deprecated --- doc/api/deprecations.md | 3 +++ doc/api/documentation.md | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index baeabb78505c1b..7fe6ec2fad307c 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -10,6 +10,8 @@ Node.js APIs might be deprecated for any of the following reasons: * An improved alternative API is available. * Breaking changes to the API are expected in a future major release. +Deprecated features are subject to [semantic versioning][] rules. + Node.js uses four kinds of deprecations: * Documentation-only @@ -4679,6 +4681,7 @@ deprecated and will throw an error in a future version. [legacy URL API]: url.md#legacy-url-api [legacy `urlObject`]: url.md#legacy-urlobject [permission model]: permissions.md#permission-model +[semantic versioning]: https://semver.org/ [static methods of `crypto.Certificate()`]: crypto.md#class-certificate [subpath exports]: packages.md#subpath-exports [subpath imports]: packages.md#subpath-imports diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 6938ac40a21374..da1e44c32864bf 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -46,7 +46,7 @@ The stability indexes are as follows: > we can know that this feature is ready to be marked as stable. > > Experimental features leave the experimental status typically either by -> graduating to stable, or are removed without a deprecation cycle. +> graduating to stable, by being deprecated, or are removed without a deprecation cycle. From 44572ae9216d6e77036d578f66c543dcc80b647a Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Fri, 27 Mar 2026 14:27:16 +0100 Subject: [PATCH 2/4] fixup! doc: clarify that features cannot be both experimental and deprecated --- doc/api/documentation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index da1e44c32864bf..13b38531fe6fc9 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -46,7 +46,9 @@ The stability indexes are as follows: > we can know that this feature is ready to be marked as stable. > > Experimental features leave the experimental status typically either by -> graduating to stable, by being deprecated, or are removed without a deprecation cycle. +> graduating to stable, or are removed without a deprecation cycle. In less +> common cases, if the feature has gotten large adoption in the ecosystem, +> they can also leave the experimental status by being deprecated. From 2cbc6bbea41d6ed00c830dd19a5618dbf3d44c28 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 31 Mar 2026 15:30:51 +0200 Subject: [PATCH 3/4] fixup! doc: clarify that features cannot be both experimental and deprecated --- doc/api/deprecations.md | 3 --- doc/api/documentation.md | 4 +--- doc/contributing/collaborator-guide.md | 11 +++++++++-- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 7fe6ec2fad307c..baeabb78505c1b 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -10,8 +10,6 @@ Node.js APIs might be deprecated for any of the following reasons: * An improved alternative API is available. * Breaking changes to the API are expected in a future major release. -Deprecated features are subject to [semantic versioning][] rules. - Node.js uses four kinds of deprecations: * Documentation-only @@ -4681,7 +4679,6 @@ deprecated and will throw an error in a future version. [legacy URL API]: url.md#legacy-url-api [legacy `urlObject`]: url.md#legacy-urlobject [permission model]: permissions.md#permission-model -[semantic versioning]: https://semver.org/ [static methods of `crypto.Certificate()`]: crypto.md#class-certificate [subpath exports]: packages.md#subpath-exports [subpath imports]: packages.md#subpath-imports diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 13b38531fe6fc9..6938ac40a21374 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -46,9 +46,7 @@ The stability indexes are as follows: > we can know that this feature is ready to be marked as stable. > > Experimental features leave the experimental status typically either by -> graduating to stable, or are removed without a deprecation cycle. In less -> common cases, if the feature has gotten large adoption in the ecosystem, -> they can also leave the experimental status by being deprecated. +> graduating to stable, or are removed without a deprecation cycle. diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index 6f2e400d440181..1b07e1f6ca4ba4 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 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 From 0560e801c9b7ffa8758eaaea0285dec03b6a01f1 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Tue, 31 Mar 2026 15:47:46 +0200 Subject: [PATCH 4/4] fixup! doc: clarify that features cannot be both experimental and deprecated --- doc/contributing/collaborator-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index 1b07e1f6ca4ba4..99b3ec84b3b9e0 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -390,8 +390,8 @@ undergo deprecation. The exceptions to this rule are: 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 should follow -[semantic versioning][] rules. +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).