doc: clarify that features cannot be both experimental and deprecated

[aduh95]

As discussed in the TSC meeting. The rationale is that either an experimental feature can be called experimental only if breaking changes (incl removal) would not break the ecosystem; if removing an experimental feature must go through a deprecation cycle, it is de facto no-longer experimental.

[nodejs-github-bot]

Review requested:

• @nodejs/userland-migrations

[JakobJingleheimer]

Shouldn't there be some way to provide advanced warning?

[aduh95]

Shouldn't there be some way to provide advanced warning?

wdym? Do you have a scenario in mind?

[joyeecheung]

I don't think this is the case for the undocumented features being deprecated.

[joyeecheung]

Suggested change

	Deprecated features are subject to [semantic versioning][] rules.
	Progression of deprecations usually follow [semantic versioning][] rules.

I think this is what you are trying to say instead? I would prefer that we leave a bit of wiggle room - I can see that we might want to deprecate things that people don't really use all that much and it's not very necessary to add the semver complexity unconditionally.

[aduh95]

No I meant to clarify that the project deprecating an experimental or undocumented API is equivalent to the project recognizing that breaking it would affect the ecosystem, i.e. setting the expectation that there won't be breaking changes to that API outside of semver major releases. (for undocumented behavior, given there's no documented behavior, a breaking change would be whatever breaks the ecosystem)

[aduh95]

I've tried to clarify what I meant in 2cbc6bb, PTAL. I think it's written in a way that would allow us to deprecate a subset of an undocumented feature the ecosystem relies on without freezing the release line

[JakobJingleheimer]

module.register() (#62395). Isn't that what precipitated this?

[joyeecheung]

Changes in doc/api/documentation.md LGTM but I think changes in doc/api/deprecations.md is a separate claim - we don't necessarily follow it for undocumented features, or I think in terms of the relationship between deprecations and semver it's always evaluated on a case-by-case basis depending on potential breakage, doesn't feel right to blanket claim it's always tied to semver...can you move that to a separate PR?

[aduh95]

I don't think undocumented features are much different from experimental ones, we don't bother going through a deprecation cycle for those – or when we do, we're putting it back into semver as we sorta guarantee it won't be removed until the end of the deprecation cycle. I'm failing to see the nuance where we can get away with a breaking change to an API yet we would deprecate it.

can you move that to a separate PR?

I'd rather not, IMO it only makes sense to land both or none.

[JakobJingleheimer]

I generally agree with this, but guidance or specific solution (eg Joyee's suggestion of "pending removal") is needed to clarify how to handle what we would otherwise call deprecation of an experimental feature. I'm not saying we need a deprecation cycle, but we need some avenue available that allows us to gently inform users (a runtime deprecation is not that).

As-is, this handcuffs a considerate user experience with what feels like "not my problem". I'm not saying that's your intention, but it does leave us wondering "well, what do we do now…".

[mcollina]

Unfortunately we had a few experimental feature that have been kept going forever and they are widely adopted because they are the only way to do things. (async_hooks, looking at you, but also others).

This is change would be correct in principle, but it would require us to revise what we have as experimental, and move what we cannot safely remove to stable (again, looking at you, async_hooks).

[aduh95]

@JakobJingleheimer @mcollina you guys approved #62395 but are blocking this PR. That seems paradoxical, the goal of this PR was to enable #62395, so I don't follow the reasoning. Is it that you think #62395 should be an exception outside of the documented process, or you disagree with the interpretation that is made in this PR?

Regarding async_hooks, I don't agree with your analysis, we're unlikely to deprecate/remove the whole of async_hooks any time soon; if we have to remove a subset of it (with non-zero user-adoption), this PR says we can deprecate that subset and avoid breaking it until it's completely removed, which AFAIK is already the status quo.

Regarding adding a new "sub-status" for experimental features pending removal, I'm certainly not against it (I'm the one who suggested it in #62395 (comment)); that being said, in the TSC meeting, deprecation seemed to be preferred, or at least that's what the discussion revolved around. That PR somewhat removes the need for that "pending removal" status, though does not conflicts with it, if someone wants to work on that.

[JakobJingleheimer]

It sounds to me like this is saying things now go from experimental directly to runtime deprecation with no "gentle" step in between. My objection is the missing middle step (where appropriate).

Or do I just not understand what the new language is saying?

I'm certainly not against it (I'm the one who suggested it in #62395 (comment))

Ack, sorry to misremember/misattribute.

[aduh95]

It sounds to me like this is saying things now go from experimental directly to runtime deprecation with no "gentle" step in between.

Hum this says nothing about runtime deprecation, only deprecation (which typically starts as doc-only).

[GeoffreyBooth]

As far as I can tell the only change in policy that this PR makes is that once something is deprecated, any further changes need to follow semver. I think part of the confusion is around what the implications are of that change, which aren’t spelled out. For example:

1. Once something is doc-deprecated, is going to runtime deprecation a semver-major change?
2. Once something is doc- or runtime-deprecated, is removal a semver-major change?

I don’t know from reading this PR what the answers are to these questions.

[aduh95]

part of the confusion is around what the implications are of that change, which aren’t spelled out

They are not spelled out in this PR, but they are spelled out already in our docs:

node/doc/contributing/collaborator-guide.md

Lines 510 to 512 in 4769b86

	Runtime Deprecations and End-of-Life APIs (internal or public) are breaking
	changes (`semver-major`). The TSC can make exceptions, deciding that one of
	these deprecations is not a breaking change.

So the answer is yes on both count

[jasnell]

Runtime-deprecations and EOL transitions have always been considered semver-major.

[GeoffreyBooth]

Runtime-deprecations and EOL transitions have always been considered semver-major.

So then what actually changes as a result of this PR? This seems to be adding words but not changing any policies?

[joyeecheung]

This is change would be correct in principle, but it would require us to revise what we have as experimental, and move what we cannot safely remove to stable (again, looking at you, async_hooks).

I think this was answered by @aduh95's thumbs up in #62456 (comment) - the stability can go:

1. 1 -> 2: stable
2. 1 -> 0: deprecated
3. 1 -> (black hole?): removed

In the case of async_hooks, it can either go 2 or 3 (likely 2 given the adoption). This PR is not suggesting 1 is the only viable path. It's clarifying 2 and 3 can also happen.

[GeoffreyBooth]

This PR is not suggesting 1 is the only viable path. It’s clarifying 2 and 3 can also happen.

Okay but that’s not a change from current policy, is it? It’s just spelling out what was already possible?

I’m not sure we want to consider adding a runtime deprecation warning to be a breaking change. That means that the path from experimental to removed either needs to be experimental -> runtime warning -> removed in next major, or experimental -> doc-deprecated -> runtime warning in next major -> removed in following major. That draws out the removal process to over two years, which feels excessive.

[ljharb]

A runtime deprecation of a non-experimental thing is always semver-major though, right? (with or without this PR)

[aduh95]

An experimental feature can be removed in a semver-patch; the warning, deprecation, waiting for next semver are all optional.

[mcollina]

lgtm

[JakobJingleheimer]

🙌 LGTM now 🙂 thank you

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/62456
✔  Done loading data for nodejs/node/pull/62456
----------------------------------- PR info ------------------------------------
Title      doc: clarify that features cannot be both experimental and deprecated (#62456)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     aduh95:experimental-to-deprecated -> nodejs:main
Labels     doc, author ready
Commits    4
 - doc: clarify that features cannot be both experimental and deprecated
 - fixup! doc: clarify that features cannot be both experimental and dep…
 - fixup! doc: clarify that features cannot be both experimental and dep…
 - fixup! doc: clarify that features cannot be both experimental and dep…
Committers 1
 - Antoine du Hamel <duhamelantoine1995@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/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>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/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>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Fri, 27 Mar 2026 09:25:25 GMT
   ✔  Approvals: 5
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/62456#pullrequestreview-4024686962
   ✔  - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/62456#pullrequestreview-4025760975
   ✔  - Jacob Smith (@JakobJingleheimer): https://github.com/nodejs/node/pull/62456#pullrequestreview-4037459211
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/62456#pullrequestreview-4037266592
   ✔  - Joyee Cheung (@joyeecheung) (TSC): https://github.com/nodejs/node/pull/62456#pullrequestreview-4037841306
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 62456
From https://github.com/nodejs/node
 * branch                  refs/pull/62456/merge -> FETCH_HEAD
✔  Fetched commits as 60f19bc0894e..0560e801c9b7
--------------------------------------------------------------------------------
Auto-merging doc/api/deprecations.md
[main 750900ea42] doc: clarify that features cannot be both experimental and deprecated
 Author: Antoine du Hamel <duhamelantoine1995@gmail.com>
 Date: Fri Mar 27 10:19:49 2026 +0100
 2 files changed, 4 insertions(+), 1 deletion(-)
[main 92f812d46a] fixup! doc: clarify that features cannot be both experimental and deprecated
 Author: Antoine du Hamel <duhamelantoine1995@gmail.com>
 Date: Fri Mar 27 14:27:16 2026 +0100
 1 file changed, 3 insertions(+), 1 deletion(-)
Auto-merging doc/api/deprecations.md
[main b88d5951a4] fixup! doc: clarify that features cannot be both experimental and deprecated
 Author: Antoine du Hamel <duhamelantoine1995@gmail.com>
 Date: Tue Mar 31 15:30:51 2026 +0200
 3 files changed, 10 insertions(+), 8 deletions(-)
[main 7a74410c1b] fixup! doc: clarify that features cannot be both experimental and deprecated
 Author: Antoine du Hamel <duhamelantoine1995@gmail.com>
 Date: Tue Mar 31 15:47:46 2026 +0200
 1 file changed, 2 insertions(+), 2 deletions(-)
   ✔  Patches applied
There are 4 commits in the PR. Attempting autorebase.
(node:490) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/5)
Rebasing (3/5)
Rebasing (4/5)
Rebasing (5/5)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
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>
[detached HEAD c36ae64b3d] doc: clarify that features cannot be both experimental and deprecated

Author: Antoine du Hamel <duhamelantoine1995@gmail.com>

Date: Fri Mar 27 10:19:49 2026 +0100

1 file changed, 9 insertions(+), 2 deletions(-)

Successfully rebased and updated refs/heads/main.

✔  c36ae64b3d303dee10e369779f3fd37dbd978f80

✔  0:0      no Co-authored-by metadata                co-authored-by-is-trailer

✔  0:0      skipping fixes-url                        fixes-url

✔  0:0      blank line after title                    line-after-title

✔  0:0      line-lengths are valid                    line-length

✔  0:0      metadata is at end of message             metadata-end

✔  1:8      PR-URL is valid.                          pr-url

✔  0:0      reviewers are valid                       reviewers

✔  0:0      valid subsystems                          subsystem

✔  0:0      Title is formatted correctly.             title-format

⚠  0:50     Title should be <= 50 columns.            title-length
The following commits are landable on origin/main

c36ae64b3d doc: clarify that features cannot be both experimental and deprecated



Removing temporary files

✔  Temporary files removed.

To finish landing:


Run:

git push origin main
Post "Landed in c36ae64b3d30" in doc: clarify that features cannot be both experimental and deprecated #62456

gh pr comment doc: clarify that features cannot be both experimental and deprecated #62456 --body "Landed in c36ae64b3d30"

gh pr close doc: clarify that features cannot be both experimental and deprecated #62456

https://github.com/nodejs/node/actions/runs/23801855942

[nodejs-github-bot]

Landed in f92c61f