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: revise deprecation level explanations in Collaborator Guide #26197

Closed
wants to merge 1 commit into from
Closed

doc: revise deprecation level explanations in Collaborator Guide #26197

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
37 changes: 19 additions & 18 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -319,24 +319,25 @@ guide](https://github.com/nodejs/node/blob/master/doc/guides/adding-new-napi-api

### Deprecations

Node.js uses three [Deprecation][] levels:

* *Documentation-Only Deprecation*: A deprecation notice is added to the API
documentation but no functional changes are implemented in the code. By
default, there will be no warnings emitted for such deprecations at
runtime. Documentation-only deprecations may trigger a runtime warning when
Node.js is started with the [`--pending-deprecation`][] flag or the
`NODE_PENDING_DEPRECATION=1` environment variable is set.

* *Runtime Deprecation*: A warning is emitted at runtime the first time that a
deprecated API is used. The [`--throw-deprecation`][] flag can be used to
escalate such warnings into runtime errors that will cause the Node.js process
to exit. As with Documentation-Only Deprecation, the documentation for the API
must be updated to clearly indicate the deprecated status.

* *End-of-life*: The API is no longer subject to the semantic versioning rules.
Backward-incompatible changes including complete removal of such APIs may
occur at any time.
Node.js uses three [Deprecation][] levels. For all deprecated APIs, the API
documentation must state the deprecation status.

* Documentation-Only Deprecation
* A deprecation notice appears in the API documentation.
* There are no functional changes.
* By default, there will be no warnings emitted for such deprecations at
runtime.
* May cause a runtime warning with the [`--pending-deprecation`][] flag or
`NODE_PENDING_DEPRECATION` environment variable.

* Runtime Deprecation
* Emits a warning at runtime on first use of the deprecated API.
* If used with the [`--throw-deprecation`][] flag, will throw a runtime error.

* End-of-life
* The API is no longer subject to the semantic versioning rules.
* Backward-incompatible changes including complete removal of such APIs 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.

Just a suggestion: should be state that End-of-life mostly means it is removed?


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 Down