doc, module: change stability of async customization hooks to experimental #60302
Conversation
|
Review requested:
|
nodejs-github-bot
added
doc
Flarna
force-pushed
the
loaderhooks-experimental
branch
2 times, most recently
from
686506b to
31c0694
Compare
Flarna
force-pushed
the
loaderhooks-experimental
branch
2 times, most recently
from
df81a7d to
f036b18
Compare
doc/api/module.md
Outdated
| <!-- type=misc --> | ||
| > Stability: 1.2 - Release candidate (asynchronous version) | ||
| > Stability: 1 - Experimental (asynchronous version) |
There was a problem hiding this comment.
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:
| > Stability: 1 - Experimental (asynchronous version) | |
| > Stability: 1.0 - Early development (asynchronous version) |
There was a problem hiding this comment.
It's not early development though
There was a problem hiding this comment.
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
There was a problem hiding this comment.
It was decided that "deprecated" was reserved for stable features:
Lines 48 to 49 in 38bf955
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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,...
mcollina
added
the
tsc-agenda
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
Co-authored-by: Antoine du Hamel <[email protected]>
Flarna
force-pushed
the
loaderhooks-experimental
branch
from
ae4d294 to
1690620
Compare
Flarna
added
the
commit-queue-squash
|
FWIW #59666 lists some of the existing bugs in the async cutomization hooks that can explain why this is a bit too far from "release candidate" (they are not yet documented as "known caveats", but have existed from v20) |
|
@mcollina you added tsc-agenda label at the same time as you approved. |
joyeecheung
removed
the
tsc-agenda
|
FYI was done at the TSC meeting; remove the tsc-agenda lebel. |
Flarna
added
the
commit-queue
nodejs-github-bot
removed
the
commit-queue
|
Landed in a59706f |
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 PR-URL: #60302 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Jacob Smith <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Darshan Sen <[email protected]>
10 participants
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