doc: update deprecations info in COLLABORATOR_GUIDE

[Trott]

The deprecations section in the COLLABORATOR_GUIDE is a bit long-winded
and repetitive. It also includes some aspirational items that appear
worded to create "an impression that a specific or meaningful statement
has been made, when instead only a vague or ambiguous claim has actually
been communicated." (Putting it in quotes because I'm copying it from
Wikipedia.)

This commit edits the text to make it more concise and meaningful.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[Trott]

As much as I don't want to bikeshed this if I can avoid it, I certainly don't want it to slip in unnoticed, so: @nodejs/tsc (Also adding the tsc-review label.)

[Trott]

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite/662/

[Trott]

Pushed a couple of minor fixes (corrected a label name, added a link to the documentatino for a CLI option). New Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite/663/

[vsemozhetbyt]

Should we as well refer to doc/api/cli.md#node_pending_deprecation1 (environment variable section) here?

[BridgeAR]

There were multiple disputes with collaborators about all the information that is now removed. So I would definitely not want to remove any of the current information but I agree that the wording here is nicer for some parts.

[BridgeAR]

I think it would be good to keep this. Especially non-native English speakers and people who are new to coding might not know what a deprecation stands for.

[mcollina]

I agree with @BridgeAR.

[trivikr]

PR to improve Deprecation definition was posted at #20788

[BridgeAR]

The semver part is important for us collaborators since it is otherwise not clear that a doc only deprecation may be semver-minor. I would be +1 for moving the notice up to the description of doc only deprecation.

[BridgeAR]

I am relatively certain that this came quite a while ago as well and it was added on purpose. So I would like to keep it to prevent confusion for collaborators.

[BridgeAR]

IMO this should be kept in here.

[BridgeAR]

I think it is good to keep it as as. This makes it clear to the reader that we try to report everything we find but we can not always handle everything. It also helps collaborators to know that this is something they should do when opening a PR.

[Trott]

I think it is good to keep it as as.

This is the paragraph most in need of removal IMO.

This makes it clear to the reader that we try to report everything we find but we can not always handle everything.

If we're trying to communicate that to the community, then the COLLABORATOR_GUIDE.md is the wrong place to do it. Information aimed at end users should be in deprecations.md instead.

Perhaps more importantly, I take issue with the idea that this paragraph makes anything clear. It is almost exclusively weasel words. The very first sentence starts with: "A best effort will be made..." What does "best effort" mean in this context? (Answer: It is meaningless. It seems significant but actually indicates nothing specific. Does that mean the Node.js Twitter will tweet out the information, for example? Maybe. No one can say. It could mean anything. So it means nothing.)

The paragraph appears to contradict itself on timing too. At the very least, the juxtaposition of "as soon as possible" with "preferably" muddies things. (Again, it all sounds like it's saying something significant but is saying nothing specific or meaningful IMO.)

If deprecations need to be disclosed to the community via one or more specific channels that Collaborators need to be aware of and responsible for, all within certain timeframes, then let's put that information in the doc. But that information does not exist and will take time to hash out. As it stands, we have a paragraph of meaningless platitudes directed at people who aren't even going to read this doc but are likely to read a different doc. Let's remove it.

It also helps collaborators to know that this is something they should do when opening a PR.

That "something they should do" is the only specific information in the paragraph and it's why I added this sentence to the doc, which is better than the existing text IMO because it clearly explains how to do the thing you're supposed to do:

Use the `notable-change` label on all pull requests that add a new deprecation
or move an existing deprecation to a new deprecation level.

[BridgeAR]

For me the first sentence seems pretty important. I understand the something should be done part as a request to check CITGM and to open PRs in userland modules to fix the upcoming issues. This is done with a "best effort" and we can not guarantee anything and decide if it makes sense to do it or not.

[mcollina]

I agree with @BridgeAR.

[mcollina]

I would prefer that the semver level of the deprecation is either in the previous list or under another heading. This is important, and it does not get enough visibility here.

[BridgeAR]

For me the first sentence seems pretty important. I understand the something should be done part as a request to check CITGM and to open PRs in userland modules to fix the upcoming issues. This is done with a "best effort" and we can not guarantee anything and decide if it makes sense to do it or not.

[BridgeAR]

When being on this: we might want to reword this that the backward-incompatible change should be done when moving something to EOL.

[BridgeAR]

@Trott is this still WIP? The deprecation information has been changed in other PRs in the meanwhile and I am not sure if you are still working on this.

[Trott]

@BridgeAR Yes, still WIP. Sorry about the delay. I'm glad the definition part got sorted, but I still have to resolve the comments on the rest of it.