Skip to content

doc, module: change stability of async customization hooks to experimental #60302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nodejs-github-bot merged 3 commits into from
Oct 22, 2025
Merged

doc, module: change stability of async customization hooks to experimental #60302

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
826da94
doc, module: change async customization hooks to experimental
Flarna Oct 17, 2025
1690620
remove changelog entry
Flarna Oct 18, 2025
55d9f19
move from 1 to 1.1
Flarna Oct 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
doc, module: change async customization hooks to experimental 
There is ongoing work to replace async customization hooks by a
synchronous variant.
As a result bugs/design flaws or the async variant (thread leak,
overhead) are not addressed.
Adapt stability index to avoid wrong assumptions they might move to
stable.

Refs: nodejs/loaders#201
Refs: nodejs/loaders#198
  • Loading branch information
@Flarna
Flarna committed Oct 18, 2025
commit 826da94bbab7d6ebf68fb525b279e7ba952cda0a
5 changes: 4 additions & 1 deletion doc/api/module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -585,6 +585,9 @@ added: v22.8.0
<!-- YAML
added: v8.8.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/60302
description: Change stability index for async variant from Release candidate to Experimental.
Comment thread
Flarna marked this conversation as resolved.
Outdated
- version:
- v23.5.0
- v22.15.0
Expand All @@ -608,7 +611,7 @@ changes:

<!-- type=misc -->

> Stability: 1.2 - Release candidate (asynchronous version)
> Stability: 1 - Experimental (asynchronous version)
Copy link
Copy Markdown
Member

@GeoffreyBooth GeoffreyBooth Oct 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any stability level 1.x is experimental. See https://nodejs.org/docs/latest/api/documentation.html#stability-index

We don’t really have a level for “pending removal” so maybe the most appropriate level is the most experimental one:

Suggested change
> Stability: 1 - Experimental (asynchronous version)
> Stability: 1.0 - Early development (asynchronous version)

Copy link
Copy Markdown
Member

@JakobJingleheimer JakobJingleheimer Oct 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not early development though

Copy link
Copy Markdown
Member Author

@Flarna Flarna Oct 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think deprecated would be the state for pending removal but that seems too early to me.

I selected a similar state/wording as for async_hooks (except the migration hints) because it seems very similar:

  • no 100% replacement as of now
  • works fine for some usecases
  • has flows which can't/are not planned to be fixed
  • high overhead at least in some cases

Copy link
Copy Markdown
Contributor

@aduh95 aduh95 Oct 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was decided that "deprecated" was reserved for stable features:

node/doc/api/documentation.md

Lines 48 to 49 in 38bf955

> Experimental features leave the experimental status typically either by
> graduating to stable, or are removed without a deprecation cycle.

Copy link
Copy Markdown
Member

@GeoffreyBooth GeoffreyBooth Oct 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just create a new stage like 1.9 - Pending removal? And we can add a note next to it that the sync hooks are the intended replacement.

Copy link
Copy Markdown
Member

@joyeecheung joyeecheung Oct 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If neither 1.2 - Release candidate nor 1.0 - Early Development makes sense, maybe 1.1 - Active development ?

I feel that whether/when to remove it would be a different question due to the existing usage, but it somewhat certain that even if it stays, it would have to have changes in order to be really functional - there are too many quirks right now.

Copy link
Copy Markdown
Member

@GeoffreyBooth GeoffreyBooth Oct 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that 1.1 - Active development is better than 1.2, but I think just making a new Pending removal stage would be better still. Worst of all would be going to just 1 - Experimental, as that doesn’t provide any guidance. Having a detailed note is good, but there’s tooling built around our docs and so I think it’s better if the most important information (that this is pending removal) is presented in a structured data way that tooling can understand, rather than contained only within a natural English note.

Copy link
Copy Markdown
Member Author

@Flarna Flarna Oct 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this PR is the right place to change the Stability index content. This can be done in a separate issue if we think this is needed. There are other places which could benefit from this (async_hooks, trace events, wasi).

Additionally I don't want to start the removal discussion as I can't tell if it will ever happen. It's experimental and according to the Stability index it can be removed at any time without a deprecation cycle. Not saying that we should do that but that is what is written there.

Reading the Stability index again it seems 1.1 fits well. While name of 1.1 includes active the detailed text says Experimental features at this stage are nearing minimum viability. which fits. There is no definition of "active" in the sense of PR count/month,...

> Stability: 1.1 - Active development (synchronous version)

There are two types of module customization hooks that are currently supported:
Expand Down