Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: update deprecations info in COLLABORATOR_GUIDE #20523

Closed
wants to merge 1 commit into from
Closed

doc: update deprecations info in COLLABORATOR_GUIDE #20523

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -463,11 +463,8 @@ Runtime Deprecation cycle. However, there is no requirement that deprecated
code must progress ultimately to *End-of-Life*. Documentation-only and runtime
deprecations may remain indefinitely.

A best effort will be made to communicate pending deprecations and associated
mitigations with the ecosystem as soon as possible (preferably before the pull
request adding the deprecation lands on the master branch). All deprecations
included in a Node.js release should be listed prominently in the "Notable
Changes" section of the release notes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@Trott Trott May 5, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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

### Involving the TSC

Expand Down