doc: clarify that features cannot be both experimental and deprecated#62456
doc: clarify that features cannot be both experimental and deprecated#62456aduh95 wants to merge 2 commits intonodejs:mainfrom
Conversation
|
Review requested:
|
|
Shouldn't there be some way to provide advanced warning? |
wdym? Do you have a scenario in mind? |
| * An improved alternative API is available. | ||
| * Breaking changes to the API are expected in a future major release. | ||
|
|
||
| Deprecated features are subject to [semantic versioning][] rules. |
There was a problem hiding this comment.
I don't think this is the case for the undocumented features being deprecated.
doc/api/documentation.md
Outdated
| > | ||
| > Experimental features leave the experimental status typically either by | ||
| > graduating to stable, or are removed without a deprecation cycle. | ||
| > graduating to stable, by being deprecated, or are removed without a deprecation cycle. |
There was a problem hiding this comment.
Clarifying question: does this mean #62395 (comment) can land because it's doing exactly the newly added exit condition? That is the transition of stability index can be:
- 1 -> 2: stable
- 1 -> 0: deprecated
- 1 -> (black hole?): removed
|
|
|
Changes in |
|
I don't think undocumented features are much different from experimental ones, we don't bother going through a deprecation cycle for those – or when we do, we're putting it back into semver as we sorta guarantee it won't be removed until the end of the deprecation cycle. I'm failing to see the nuance where we can get away with a breaking change to an API yet we would deprecate it.
I'd rather not, IMO it only makes sense to land both or none. |
5 participants
As discussed in the TSC meeting. The rationale is that either an experimental feature can be called experimental only if breaking changes (incl removal) would not break the ecosystem; if removing an experimental feature must go through a deprecation cycle, it is de facto no-longer experimental.