Skip to content

Confirmation that the stability definition is correct #12701

Closed
@sam-github

Description

@sam-github

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 experimental explicitly states that the API is subject to change in a future version. It doesn't even say "future major version"! This means that experimental APIs are explicitly NOT subject to the deprecation process.

While any individual package author is (hopefully) aware that they are using an experimental API 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 when experimental APIs are called (perhaps it should?), npm doesn't refuse to install dependencies that rely on experimental APIs (how could it know?), so its very easy for a user to become dependent on experimental features.

In my opinion, the case for gating experimental APIs 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 on experimental node APIs, and expect no guarantee of stability.

Doing this allows node to treat experimental APIs the way the docs say we do: experiments we can change or withdraw at will.

Without a flag, we cannot do that. experimental APIs 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 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.

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 experimental APIs.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions