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/2] 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/2] 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.