doc: update experimental status to reflect use #12723
Conversation
|
I'm not exactly OK with locking ourselves into experimental features... This is exactly what we moved away from, what we had and worked out poorly in the past. |
doc/api/documentation.md
Outdated
| This feature is still under active development and subject to non-backwards | ||
| compatible changes, or even removal, in any future version. Use of the feature | ||
| is not recommended in production environments. The feature may only be usable | ||
| only after using a command-line flag to enable it. Use of the feature may cause |
| ``` | ||
|
|
||
| ```txt | ||
| Stability: 1 - Experimental | ||
| This feature is subject to change, and is gated by a command line flag. | ||
| It may change or be removed in future versions. | ||
| This feature is still under active development and subject to non-backwards |
There was a problem hiding this comment.
Here you use this, while everywhere else you use the
There was a problem hiding this comment.
Yes, this is consistent with the existing language. For instance, under deprecated, it starts with 'This feature' and has the feature in the next sentence.
@Fishrock123 May I ask in what sense are we locking ourselves? Do you feel that defining
Could you share an example? (honest question!) Correct me if I'm wrong, but as I see it the alternatives are:
|
The change here is from "experimental means behind a flag" to "experimental might mean behind a flag". I assume @Fishrock123 was referring to discussion in #12701. |
|
FWIW I'm -1 on this. Once |
|
Async_hooks is still experimental and not behind a flag. |
|
@Fishrock123 ... It's not clear at all what you mean by "locking ourselves in to experimental features" |
jasnell
force-pushed
the
update-experimental
branch
from
9d5d246
to
6ec61a5
Compare
|
@nodejs/ctc ... PTAL |
On «Experimental»Um. It's not great that we introduce APIs that are exprected to change and are not behind the flag. Given how the ecosystem actually uses the API, we had problems even changing undocumented API (and got yelled at for that). I don't think that introducing more unflagged API that is expected to change will improve the situation here. How about we just flag everything new until it's ready, like Chromium/V8 does? I suppose that we need a discussion about this. On «Deprecated»The new description in fact contradicts with the recent decision about the old Buffer API. It is currently deprecated in a sense that a complete drop-in replacement exists and that the old API usage is highly discouraged, but we recently decided on a CTC vote that we do not plan any changes there at this point. The description in this PR directly contradicts that. |
That’s because those APIs were the opposite of experimental, though; they had been around for so long that they basically had to be considered part of the public API, whereas experimental APIs are quite fresh (usually too young to have a significant share of the ecosystem come to rely on them, flagged or unflagged).
I think I’d be -1 on doing that unconditionally, Node’s ecosystem has a different way of adopting new features than JavaScript itself. I agree with what you say about “Deprecated”, though. |
|
I've seen absolutely no evidence to support the position that explicitly opt-in APIs must be put behind a flag. Recent experience has shown exactly the opposite. If we look at recent history with experimental features that (a) were not behind a flag and (b) had no documented issues of causing any problems (for instance, WHATWG URL and async-hooks), I think that it should be fairly clear that a flag is not strictly necessary if we're quite clear on the documentation and user expectations side of things. |
|
Regarding async-hooks: The async-hooks API doesn't exist in the master branch, the PR is still open. Its predecessor async-wrap does however exist. The Diagnostic WG calls the async-wrap API pre-experimental since it is purposely kept undocumented, can only be accessed using It would truly surprise me if there are more than 10 people in the world that use async-wrap directly, thus it is not a good candidate for measuring "documented issues". |
|
Note: my -1 is mostly for the For changing the definition of |
ChALkeR
dismissed
their stale review
There are no actual changes in the Deprecated description.
|
Sorry, it looks like I made a mistake — I have dismissed my review. I will open a new issue for the problem with the That said, I would want to see more acknowledgement from @nodejs/ctc members on the |
doc/api/documentation.md
Outdated
| It may change or be removed in future versions. | ||
| This feature is still under active development and subject to non-backwards | ||
| compatible changes, or even removal, in any future version. Use of the feature | ||
| is not recommended in production environments. The feature may only be usable |
There was a problem hiding this comment.
nit:
s/The feature may only be usable The feature may only be usable/The feature may require the use of a command-line flag to enable it
|
@chrisdickinson PTAL, this removes text you added in #943 @isaacs You experienced API lock-in, you may have comments on this and/or #12701 |
|
I still don't agree with this. There is a long history of js code depending on undocumented node properties, APIs, and behaviours and Node.js being locked into inability to make changes we want to, I agree with #12723 (comment) While I agree that that the URL and async-wrap were not a source of problems, I think they have some very unique characteristics, and don't convince me that "the times have changed". URL implements an API that was pre-specified and much discussed by the WhatWG before it was implemented in Node, which makes it a very atypical "experimental" API (I think its actually unique in Node, we have no other APIs externally specified). async-wrap, #12723 (comment), was a fringe API, not likely to be widely used, and arguably not very useful for its target users (thus its successor, async-hooks). Also, as far as I know, we have not deleted it yet, so we may yet hear screaming (though I don't expect we will). |
|
@sam-github ... ok, I'll think through this a bit more. That said, one notable experimental feature that we're going to have coming up soon is http/2. That is entirely new code that would have zero impact on existing code and it's use is completely opt-in. Other than the potential for people using it before it's done (and therefore having to put up with breaking changes), there is, in theory, no technical reason it would need to be behind a flag -- we may want to do so, but there's no detrimental technical impact if we do not do so. With that, there are two approaches:
Option one is stricter, option two is far more lenient. I guess the choice, then, comes down to how much we want to try to protect users against themselves :-) |
jasnell
force-pushed
the
update-experimental
branch
from
6ec61a5
to
314b787
Compare
|
Updated the text per discussion. PTAL |
|
As stated in #9036, which @jasnell agreed with at the time, I think we should print warnings for all experimental features. In addition, i think we need to reserve, by default, the ability to change or remove experimental APIs. I think we can consider, outside of the default to do something different if need be for our users, but I think it should be assumed to be able to change at any time until marked as Stable. |
|
This came up in the last @nodejs/diagnostics WG meeting, nodejs/diagnostics#94 @ofrobots and @watson stated that there products would not use an API if using caused warnings to be emitted and used by users, which I agree with, strong-agent would not have done that either, any warnings that user's see are considered bugs by users, so not acceptable in production code. But I think this calls into question the purpose of "experimental". In my opinion, this is somewhere where we should be more similar to Chrome. It can be difficult to get feedback on APIs while they still exist on PR branches, its a fairly small group of users who are willing to compile Chrome or Node in order to try out a feature. We land these features on master (and then Current) so that users can experiment with them, but in Chrome, you still have to turn on experimental features in chrome://flags/, the node equivalent is a CLI (and we expose CLI options via The purpose is to make it simultaneously:
I don't have a crystal ball. Its possible that async hooks, or the js inspector API (#12263) will land as "docs only" experimental, and either we don't find need to make backwards incompatible changes to them, or that not enough people are using them to notice when we do change them. Maybe people will treat the docs seriously, I'm willing to give it a try, but I think its risky, I'd rather hide experimental features behind flags, like Chrome does, and then advertise them widely via twitter/node roundup/etc. so we can get feedback on them, and work on getting them stable quickly (and backported to LTS if at all possible). |
This is rather the point. We do not want these going into production environments and if emitting a warning provides enough discouragement to do so, then a flag is not necessary. |
One problem is that they "won't be able" to use those features once the warning is disabled either. Because it would be hard or even impossible to test if the feature still generates a warning. They would need to guard everything with node version checks because the existence of a function or module wouldn't mean that it can be used w/o noisy warnings. |
|
Its nice to have simple testing of existence of a feature, but we already do semver comparisons on node's version, how we monkey-patch http.get depends on the version (since http.get doesn't call http.request anymore as it used to). |
|
Landing given the sign off... |
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
|
Landed in 5c2d1af |
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
|
I think this is a big step backwards, but ¯\_(ツ)_/¯ I guess. |
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
* Update the experimental status to reflect actual common use. * Also make a few formatting fixes. Fixes: #12701 PR-URL: #12723 Fixes: #12701 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]>
Fixes: #12701
Checklist
Affected core subsystem(s)
doc