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

doc: deprecation clarifications #19522

Closed
wants to merge 3 commits into from
Closed

doc: deprecation clarifications #19522

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11c3a41
doc: deprecation clarifications
jasnell Mar 21, 2018
cb84aaa
[Squash] address feedback
jasnell Mar 22, 2018
4c9c281
[Squash] nits
jasnell Mar 24, 2018
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
24 changes: 15 additions & 9 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -403,10 +403,11 @@ recommended but not required.

### Deprecations

_Deprecation_ refers to the identification of Public APIs that should no longer
be used and that may be removed or modified in backward-incompatible ways in
a future major release of Node.js. Deprecation may be used with internal APIs if
there is expected impact on the user community.
__Deprecation__ refers to the identification of Public APIs that should no
longer be used.

Once specific bits of code are marked as being Deprecated, they are no longer
Copy link
Member

@Trott Trott Mar 21, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

specific bits of code are marked as being Deprecated -> APIs are deprecated

covered by the typical current or Long Term Support policies.
Copy link
Member

@Trott Trott Mar 21, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

Remove typical or current. More importantly, what does this mean? Is this all about semver or is it something else?

Copy link
Member Author

Choose a reason for hiding this comment

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

For instance, a deprecated function in an LTS branch would not fall under the same scrutiny and care as a non-deprecated function in that same branch, meaning we may be more liberal about what changes we allow to be made within those

Copy link
Member

Choose a reason for hiding this comment

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

Can we link to these policies here?


Node.js uses three Deprecation levels:

Expand All @@ -415,9 +416,9 @@ Node.js uses three Deprecation levels:
notice indicating the deprecated status is added to the API documentation
but no functional changes are implemented in the code. There will be no
runtime deprecation warnings emitted for such deprecations by default.
Documentation-only deprecations may trigger a runtime warning when launched
with [`--pending-deprecation`][] flag (or its alternative,
`NODE_PENDING_DEPRECATION=1` environment variable).
Documentation-only deprecations may trigger an opt-in only runtime warning
Copy link
Member

Choose a reason for hiding this comment

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

I'm not sure "opt-in only" is necessary

Copy link
Member

Choose a reason for hiding this comment

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

an opt-in only runtime warning -> a runtime warning

when Node.js is launched with the [`--pending-deprecation`][] flag (or its
alternative, `NODE_PENDING_DEPRECATION=1` environment variable).
Copy link
Member

@Trott Trott Mar 21, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

(or its alternative, `NODE_PENDING_DEPRECATION=1` environment variable) -> or if the `NODE_PENDING_DEPRECATION` environment variable is set.

Copy link
Member Author

Choose a reason for hiding this comment

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

the value specifically needs to be NODE_PENDING_DEPRECATION=1


* *Runtime Deprecation* refers to the use of process warnings emitted at
runtime the first time that a deprecated API is used. A command-line
Expand All @@ -427,7 +428,9 @@ Node.js uses three Deprecation levels:
deprecated status.

* *End-of-life* refers to APIs that have gone through Runtime Deprecation and
are ready to be removed from Node.js entirely.
are no longer subject to the semantic-versioning and support policies used by
Copy link
Member

Choose a reason for hiding this comment

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

"semantic versioning" without dash

Copy link
Member

Choose a reason for hiding this comment

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

Can we link to these policies here?

the project. Backward-incompatible changes or even complete removal of such
Copy link
Member

Choose a reason for hiding this comment

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

or even -> including

code may occur at any time.
Copy link
Member

Choose a reason for hiding this comment

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

code -> APIs


Documentation-Only Deprecations may be handled as semver-minor or semver-major
changes. Such deprecations have no impact on the successful operation of running
Expand All @@ -452,7 +455,10 @@ Deprecations may land in a Node.js minor release but must not be upgraded to
a Runtime Deprecation until the next major release.)

No API can be moved to End-of-life without first having gone through a
Runtime Deprecation cycle.
Runtime Deprecation cycle. However, there is no requirement that deprecated
code must progress ultimately to *End-of-Life*. It is possible, and at times
preferable, for code that is documentation-only or runtime deprecated to
remain so indefinitely.
Copy link
Member

Choose a reason for hiding this comment

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

It is possible, and at times preferable, for code that is documentation-only or runtime deprecated to remain so indefinitely. -> 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
Expand Down