Changing Definition of "Locked" for Stability Index in API Docs

[MylesBorins]

As discussed in last weeks @nodejs/ctc meeting

Currently our api docs have a stability index with fairly conservative definition of Locked

Stability: 3 - Locked
Only bug fixes, security fixes, and performance improvements will be accepted.
Please do not suggest API changes in this area; they will be refused.

This 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 it

A suggested alternative text

Stability: 3 - Locked
Only bug fixes, security fixes, and performance improvements will be accepted.
Please do not suggest API changes in this area; they will be refused. Locked APIs
are subject to change to support new language features that are added to the ecma262
specification.

Thoughts?

[targos]

Looks good to me, with s/ecma262/ECMA-262/.

[Trott]

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.md in the section that lists/explains the stability indexes.

[bnoordhuis]

I like Rich's suggestion.

[jasnell]

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 of Buffer. 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.

[Trott]

@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.

[rvagg]

+1 although I'd go with "may be considered" rather than "are permitted"

[ChALkeR]

Not 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 assert and/or timers,
• assert: introduce deepStrictEqual #639 ­— deepStrictEqual in assert,
• 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.

[Trott]

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.

[ChALkeR]

@Trott

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.deepStreetEqual landed as a brand new feature while assert module 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.

[ChALkeR]

I personally think that with #7964 in place, we could move away from the «Locked» concept entirely (re-label those three modules as Stable).

And that would match with how we have been actually dealing with patches to those modules.