meta: deprecation policy #7964
meta: deprecation policy #7964
Conversation
jasnell
added
the
meta
COLLABORATOR_GUIDE.md
Outdated
| @@ -73,6 +73,70 @@ All pull requests that modify executable code should be subjected to | |||
| continuous integration tests on the | |||
| [project CI server](https://ci.nodejs.org/). | |||
|
|
|||
| ## Semver-major Changes | |||
There was a problem hiding this comment.
Nit: Use "Breaking Changes" or some other generally-used terminology? My experience, at least, is that while "semantic versioning" is widely understood, the term "semver major" is confusing to people who have not heard it before. I have not encountered it outside of nodejs repos.
|
Tons of nits, but no major objections. LGTM. |
|
Updated! |
COLLABORATOR_GUIDE.md
Outdated
| * Soft-Deprecation (or Docs-only deprecation) refers to elements of the Node.js | ||
| public API that are being staged for deprecation in a future Node.js major | ||
| release. An explicit notice indicating the deprecated status is added to the | ||
| API documentation *but no functional changes are implemented in the code. |
jasnell
force-pushed
the
deprecation-cycle
branch
from
80fba8b
to
4148d87
Compare
|
fixed nits and added some additional discussion detail. PTAL |
| the documentation for the API must be updated to clearly indicate the | ||
| deprecated status. | ||
|
|
||
| * *End-of-life* refers to APIs that have gone through Runtime Deprecation and |
There was a problem hiding this comment.
Shouldn't we remove APIs at this level?
There was a problem hiding this comment.
yes, the idea is that marking an API end-of-life means that it can be removed at any time, it just may not be removed right away.
There was a problem hiding this comment.
@jasnell Once they reach this level, we will remove them from docs as well. Should we even mention level?
There was a problem hiding this comment.
They'll be removed from the main docs, but they will still be listed in the deprecations.md documentation page that lists the various deprecation identifiers.
| changes to a *Public* API are necessary, the existing API *must* be deprecated | ||
| *first* and the new API either introduced in parallel or added after the next | ||
| major Node.js version following the deprecation as a replacement for the | ||
| deprecated API. In other words, as a general rule, existing *Public* APIs |
There was a problem hiding this comment.
One challenge here is that, at present, there is no such contract between Node.js and the VMs that any VM provided API that Node.js exposes must go through the same 6mo+ deprecation cycle. Either we need to co-ordinate with VM on being able to offer this guarantee on exposed VM APIs, or we should explicitly call this out in the exceptions below.
In practice, as in the old debug protocol example recently, we have the ability to work/negotiate with the VMs to figure out the timeline – the problems is that the VMs may not necessarily know what parts of their APIs are being exposed by Node, and the kind of a deprecation guarantee Node intends to provide for these APIs that the VM needs to uphold.
There was a problem hiding this comment.
Found this comment: #7964 (comment). I'd be fine with dealing with this in a follow-on.
jasnell
force-pushed
the
deprecation-cycle
branch
from
a0e97a6
to
dc9e99d
Compare
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface
jasnell
force-pushed
the
deprecation-cycle
branch
from
dc9e99d
to
305a354
Compare
|
@sam-github @ofrobots just pushed a couple of edits that hopefully clarify a few bits. Specifically on your comments @ofrobots ... there is an explicit statement that APIs, behaviors and errors from dependencies fall outside the scope of this policy but need to be taken into consideration when landing updates. |
|
Given the reviews, I believe this is ready to go ahead and land. |
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: #7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
|
Landed in e5bd880 |
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: nodejs#7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: nodejs#7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: #7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: #7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: #7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface PR-URL: #7964 Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sam Roberts <[email protected]> Reviewed-By: Trevor Norris <[email protected]> Reviewed-By: Сковорода Никита Андреевич <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
Checklist
Affected core subsystem(s)
meta
Description of change
First step at documenting the deprecation requirements.
Refs: #7955
/cc @nodejs/ctc