Repository navigation
Changing Definition of "Locked" for Stability Index in API Docs #11200
Description
Activity
Looks good to me, with
s/ecma262/ECMA-262/.I have mixed feelings.
I think the last sentence seems to contradict the first two sentences (with an emphasis on seems).
I also wonder if the new sentence is more directed at ourselves than a typical contributor. Like, instead of "It can be argued that this is already covered by bug fixes", I would say that is in fact the plain reading of the text. I think the whole "will reject attempts to accommodate actual language features" was a result of us not adhering to that text and instead trying to use Locked as this strange we-get-to-have-it-both-ways "no, we're not deprecating this, but it's not for you and you shouldn't use it" statement.
Maybe the actual Locked text can be left alone in all its wonderful brevity (and in fact, if anything, it could be made more brief by simply removing the second sentence as it is redundant) and we can instead add this additional information as explanatory text that isn't part of the ends-up-in-a-bannerish-box-in-the-docs text:
```txt Stability: 3 - Locked Only bug fixes, security fixes, and performance improvements will be accepted. ``` Changes to support new language features that are added to the ECMA-262 specification are considered bug fixes and are therefore permitted in Locked APIs.
EDIT: That would be in
document.mdin the section that lists/explains the stability indexes.I like Rich's suggestion.
I'm not that comfortable classifying all changes to support new language features as bug fixes. Some of them are flat out API changes. For instance, if TC-39 adds a new method to
Uint8Array, then that becomes a new API feature ofBuffer. It's not a "fix". I would word it differently, then:Changes to support new language features that are added to the ECMA-262 specification are handled independently of this stability index and are permitteed in Locked APIs.@jasnell suggested:
Changes to support new language features that are added to the ECMA-262
specification are handled independently of this stability index and are permitteed
in Locked APIs.Remove "handled independently of this stability index" (does not impart any useful information, just raises questions and muddies the otherwise clear meaning) and you've got something good, I think:
Changes to support new language features that are added to the ECMA-262 specification are permitted in Locked APIs.Reacted by Sean Vieira+1 although I'd go with "may be considered" rather than "are permitted"
Reacted by Rich TrottNot sure about this (the part that limits the allowed changes to ecma262-induced).
As this looks to me, the proposed wording does not cover changes in #10282.It also doesn't seem to cover other changes that landed to «Locked» modules not so long ago, e.g.:
- Consistent error messages in all modules #3374, assert: use util.inspect() to create error messages #668 — error message changes in
assertand/ortimers, - assert: introduce
deepStrictEqual#639 —deepStrictEqualinassert, - timers: Fail early when callback is not a function #4362 —
timers: Fail early when callback is not a function, - module: preserve symlinks when requiring #5950, module: prioritize current directory for local lookup #5689, src: fix module search path for preload modules #1812, module: restore and warn on require('.') usage with NODE_PATH #1363 — module loading changes in
modules.
Note: the list above is outdated, there are probably newer ones.
- Consistent error messages in all modules #3374, assert: use util.inspect() to create error messages #668 — error message changes in
Not sure about this (the part that limits the allowed changes to ecma262-induced).
I don't think there's any language that limits anything to ecma262-related stuff, or at least that's not my intention. It's supposed to explicitly allow ecma262-related stuff, but not necessarily limit it to just that.
Perhaps that's an argument for leaving it out entirely and just going with:
```txt Stability: 3 - Locked Only bug fixes, security fixes, and performance improvements will be accepted. ```
We decided at the CTC meeting that things like "make assert.deepStrictEqual() work as expected with Maps and Sets" could be considered a bug fix (on a case-by-case basis) but we don't necessarily have to get into that level of detail in our docs about the Stability Index.
We decided at the CTC meeting that things like "make assert.deepStrictEqual() work as expected with Maps and Sets" could be considered a bug fix (on a case-by-case basis)
What I am talking about is that
assert.deepStreetEquallanded as a brand new feature whileassertmodule had already been «locked» for some time. (That is one example, but there are more of major/minor changes to those modules in the git log).That is either a bug in the process of accepting patches to those three modules (modules, timers, assert) or a bug in the documentation of that process. If the former, then no such pull requests should have been accepted at the first place, and shouldn't be accepted in the future. If the latter, the stability index documentation needs a more severe change that covers the way how we have been actually dealing with accepting patches to those modules in a clear way.
Now the actual process breaks users expectations, as it significantly differs from what is documented — we can't keep saying that those modules accept only bugfixes and keep accepting semver-major and semver-minor level changes there, we have to choose something.
That is either a bug in the process of accepting patches to those three modules (modules, timers, assert) or a bug in the documentation of that process.
IMO, it's the former.
and keep accepting semver-major and semver-minor level changes there
I don't think that's the plan.
I personally think that with #7964 in place, we could move away from the «Locked» concept entirely (re-label those three modules as Stable).
Works for me if I'm wrong and we do plan on accepting semver-minor and semver-major on currently Locked APIs.
36 remaining items
- added 2 commits that reference this issue
on Mar 7, 2017 - added 2 commits that reference this issue
on Mar 7, 2017 - added 2 commits that reference this issue
on Mar 9, 2017 - added 3 commits that reference this issue
on Jul 19, 2017
As discussed in last weeks @nodejs/ctc meeting
Currently our api docs have a stability index with fairly conservative definition of
LockedThis has been fairly useful when discussing changes to APIs that are potentially breaking, such as any change to the module system. With changes coming to the ecma262 standard on a yearly basis now, we find ourselves in a slightly different situation then when this was originally drafted. As the language changes we may be required to change locked APIs, such as assert or module, in order to accommodate the changes to the language.
It can be argued that this is already covered by
bug fixes, but that is somewhat ambiguous, and it would be better to be explicit about itA suggested alternative text
Thoughts?