Repository navigation
Confirmation that the stability definition is correct #12701
Description
Activity
@nodejs/ctc
I think that having
$NODE_OPTIONS(#12028) makes putting things behind a flag much more feasible.Putting experimental things behind a flag is not something that we have consistently done.
I get that we haven't done it in the past, why we wouldn't want to always do this in the future? Users depending on an immature API seems like a real problem, and not one that's fixable after the fact.
why we wouldn't want to always do this in the future
Because I don't see it as being necessary if use of the API is entirely opt in and the documentation is clear about it being experimental.
Reacted by Anna HenningsenURL is a case of something that should have been gated behind a CLI flag, or declated stable from the start. It was developed based on a fairly stable specification, and doesn't appear to have ever had breaking changes proposed (that I noticed), but if we had been forced to make breaking changes it could have been very painful for the ecosystem.
I disagree with that. We had to make several changes to the URL implementation for spec compliance and they would have been semver-major if the stability index wasn't
experimental.@targos You quoted to much, what is "that"? You disagree it should have been behind a flag? You disagree it could have been painful for the ecosystem? You disagree that there were breaking changes that I noticed? Surely not that last.
@jasnell We had APIs in node for years (cluster, I'm looking at you) that node labelled
experimental, but were treated wrt. to stability as "cannot change". There is a long history of not being able to change APIs even withexperimentalblazoned across the top, which frustrates the purpose ofexperimental.This is not the case:
use of the API is entirely opt in and the documentation is clear about it being experimental.
The author of the code may know they are depending on
experimental, but the indirect consumer of the API via npm dependencies has literally no way to know ATM if they depend on experimental APIs.To be clear: I don't have a problem with experimental APIs, I don't have a problem with breaking them, I don't have a problem with URL or inspector or anything else we want to get community feedback on being published in node as an experimental API, I have a problem with not having experimental APIs be explicitly opt-in, making npmjs.org a minefield.
Also, I quite like the idea of experimental APIs emitting process warnings. That could be an alternative to CLI opt-in. Its not opt-in, but it allows the end user to know they have inherited a dependency on
experimentalcode.Reacted by Refael AckermannI'm certainly open to having future experimental APIs emit warnings when used.
[question]
Is it your experience that people always update thenodeexecutable?[opinion]
From my experience there are two "general" cases:- developers - usually update often, get frustrated when stuff breaks -> push-back. But they have the flexibility and knowledge how to adapt.
- production - once a system works everything is frozen (to the point of ignoring CVE fixing
semver-patchupdates), because they don't have the flexibility to adapt.
IMHO we need to think of these two separate groups' needs, and constraints/flexibility
[radical opinion]
If we feel we are doing something really important, we should be able to withstand push-back from frustrated devs, since they have the means to adapt.- added a commit that references this issue
on May 11, 2017 The definition of
experimentalexplicitly states that the API is subject to change in a future version. It doesn't even say "future major version"! This means thatexperimentalAPIs are explicitly NOT subject to the deprecation process.I would say this is correct. By default, they are not subject to it but we may consider it if so necessary for our users.
- added a commit that references this issue
on Jul 24, 2017 - added 3 commits that reference this issue
on Aug 16, 2017 - added 2 commits that reference this issue
on Sep 3, 2017 - added a commit that references this issue
on Jul 27, 2026
cf. #12670 (comment)
@addaleax thinks the stability definition is wrong for
experimental:https://nodejs.org/api/documentation.html#documentation_stability_index
I don't agree, and would like confirmation that the docs are correct.
Node cannot break the ecosystem by changing or removing its APIs without going through its deprecation process (even the deprecation process can cause lots of kick-back, we all remember Buffer).
The definition of
experimentalexplicitly states that the API is subject to change in a future version. It doesn't even say "future major version"! This means thatexperimentalAPIs are explicitly NOT subject to the deprecation process.While any individual package author is (hopefully) aware that they are using an
experimentalAPI with no stability guarantees when they type their javascript code out that uses the API, and are comfortable with the risk, users of their package have no way to know. Node doesn't write warning messages to stderr whenexperimentalAPIs are called (perhaps it should?), npm doesn't refuse to install dependencies that rely onexperimentalAPIs (how could it know?), so its very easy for a user to become dependent onexperimentalfeatures.In my opinion, the case for gating
experimentalAPIs via a command line flag is to force the end consumer of a package, perhaps a consumer seperated by many layers of package depencies, to explicitly recognize that they are depending onexperimentalnode APIs, and expect no guarantee of stability.Doing this allows node to treat
experimentalAPIs the way the docs say we do: experiments we can change or withdraw at will.Without a flag, we cannot do that.
experimentalAPIs are part of our API, and we can't and won't break them (whatever the docs say).Inspector is an odd case of experimental. It was gated behind a flag, but only because all debugging is gated :-). It will still be behind a CLI flag when its not experimental.
URL is a case of something that should have been gated behind a CLI flag, or declated
stablefrom the start. It was developed based on a fairly stable specification, and doesn't appear to have ever had breaking changes proposed (that I noticed), but if we had been forced to make breaking changes it could have been very painful for the ecosystem.Those are the past, though, I'm more worried about the future, and would like to see agreement that the text is correct, and describes our intentions with any future
experimentalAPIs.