doc: clarify that features cannot be both experimental and deprecated by aduh95 · Pull Request #62456 · nodejs/node

aduh95 · 2026-03-27T09:25:25Z

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 · 2026-03-27T09:25:30Z

Review requested:

@nodejs/userland-migrations

JakobJingleheimer · 2026-03-27T09:37:18Z

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

aduh95 · 2026-03-27T09:52:06Z

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

wdym? Do you have a scenario in mind?

joyeecheung · 2026-03-27T10:46:19Z

doc/api/deprecations.md

 * 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.


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

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.

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)

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

doc/api/documentation.md

JakobJingleheimer · 2026-03-27T11:21:39Z

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

…recated

joyeecheung · 2026-03-27T18:33:07Z

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 · 2026-03-28T00:00:35Z

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 · 2026-03-29T16:31:55Z

@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 · 2026-03-29T16:42:18Z

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 · 2026-03-29T16:54:03Z

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 · 2026-03-29T17:47:30Z

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:

Once something is doc-deprecated, is going to runtime deprecation a semver-major change?
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 · 2026-03-29T19:11:30Z

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 · 2026-03-29T23:46:01Z

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

GeoffreyBooth · 2026-03-30T01:02:56Z

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 · 2026-03-30T16:04:44Z

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 -> 2: stable
1 -> 0: deprecated
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 · 2026-03-30T19:37:20Z

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 · 2026-03-30T20:00:17Z

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

aduh95 · 2026-03-30T21:09:57Z

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

doc/api/documentation.md

mcollina

lgtm

…recated

JakobJingleheimer

🙌 LGTM now 🙂 thank you

…recated

nodejs-github-bot · 2026-03-31T14:46:46Z

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 · 2026-03-31T14:52:39Z

Landed in f92c61f

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>

doc: clarify that features cannot be both experimental and deprecated

92cb53a

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Mar 27, 2026

joyeecheung reviewed Mar 27, 2026

View reviewed changes

fixup! doc: clarify that features cannot be both experimental and dep…

44572ae

…recated

jasnell approved these changes Mar 28, 2026

View reviewed changes

GeoffreyBooth mentioned this pull request Mar 28, 2026

module: doc-deprecate module.register() #62395

Merged

GeoffreyBooth approved these changes Mar 28, 2026

View reviewed changes

AugustinMauroy approved these changes Mar 28, 2026

View reviewed changes

JakobJingleheimer requested changes Mar 28, 2026

View reviewed changes

mcollina requested changes Mar 28, 2026

View reviewed changes

aduh95 mentioned this pull request Mar 30, 2026

module: runtime deprecate module.register() #62401

Open

JakobJingleheimer reviewed Mar 31, 2026

View reviewed changes

doc/api/documentation.md Outdated Show resolved Hide resolved

JakobJingleheimer reviewed Mar 31, 2026

View reviewed changes

doc/api/documentation.md Outdated Show resolved Hide resolved

mcollina approved these changes Mar 31, 2026

View reviewed changes

fixup! doc: clarify that features cannot be both experimental and dep…

2cbc6bb

…recated

JakobJingleheimer approved these changes Mar 31, 2026

View reviewed changes

fixup! doc: clarify that features cannot be both experimental and dep…

0560e80

…recated

aduh95 requested a review from joyeecheung March 31, 2026 13:51

joyeecheung approved these changes Mar 31, 2026

View reviewed changes

aduh95 added author ready PRs that have at least one approval, no pending requests for changes, and a CI started. commit-queue Add this label to land a pull request using GitHub Actions. labels Mar 31, 2026

nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels Mar 31, 2026

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Mar 31, 2026

nodejs-github-bot merged commit f92c61f into nodejs:main Mar 31, 2026
35 checks passed

aduh95 deleted the experimental-to-deprecated branch March 31, 2026 14:56

aduh95 mentioned this pull request Mar 31, 2026

2026-04-01, Version 25.9.0 (Current) #62522

Open

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

Uh oh!

Conversation

aduh95 commented Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 27, 2026

Uh oh!

JakobJingleheimer commented Mar 27, 2026

Uh oh!

aduh95 commented Mar 27, 2026

Uh oh!

joyeecheung Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

joyeecheung Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JakobJingleheimer commented Mar 27, 2026

Uh oh!

joyeecheung commented Mar 27, 2026

Uh oh!

aduh95 commented Mar 28, 2026

Uh oh!

JakobJingleheimer left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcollina left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JakobJingleheimer commented Mar 29, 2026

Uh oh!

aduh95 commented Mar 29, 2026

Uh oh!

GeoffreyBooth commented Mar 29, 2026

Uh oh!

aduh95 commented Mar 29, 2026

Uh oh!

jasnell commented Mar 29, 2026

Uh oh!

GeoffreyBooth commented Mar 30, 2026

Uh oh!

joyeecheung commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

GeoffreyBooth commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ljharb commented Mar 30, 2026

Uh oh!

aduh95 commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Mar 31, 2026

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>

Uh oh!

Uh oh!

nodejs-github-bot commented Mar 31, 2026

Uh oh!

aduh95 commented Mar 27, 2026 •

edited

Loading

joyeecheung Mar 30, 2026 •

edited

Loading

aduh95 Mar 30, 2026 •

edited

Loading

JakobJingleheimer left a comment •

edited

Loading

mcollina left a comment •

edited

Loading

aduh95 commented Mar 29, 2026 •

edited

Loading

joyeecheung commented Mar 30, 2026 •

edited

Loading

GeoffreyBooth commented Mar 30, 2026 •

edited

Loading

aduh95 commented Mar 30, 2026 •

edited

Loading

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>