meta: deprecation policy by jasnell · Pull Request #7964 · nodejs/node · GitHub

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

Description of change

First step at documenting the deprecation requirements.
Refs: #7955
/cc @nodejs/ctc

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!

missing closing *?

Fixed!

fixed nits and added some additional discussion detail. PTAL

Shouldn't we remove APIs at this level?

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.

@jasnell Once they reach this level, we will remove them from docs as well. Should we even mention level?

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.

LGTM, this is great.

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.

Found this comment: #7964 (comment). I'd be fine with dealing with this in a follow-on.

* Formalizes deprecation policy * Introduces End-of-life deprecation phase to identify code to be removed * Outlines basics of internal vs. public API surface

@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 <evanlucas@me.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

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 <evanlucas@me.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

* 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 <evanlucas@me.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Trevor Norris <trev.norris@gmail.com> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

jasnell added the meta Issues and PRs related to the general management of the project. label Aug 3, 2016

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 3, 2016

Trott reviewed Aug 3, 2016
View reviewed changes

addaleax reviewed Aug 3, 2016
View reviewed changes

jasnell force-pushed the deprecation-cycle branch from 80fba8b to 4148d87 Compare August 4, 2016 18:25

ChALkeR mentioned this pull request Aug 5, 2016

buffer: throw on negative .allocUnsafe() argument #7079

Closed

3 tasks

This was referenced Jan 27, 2017

doc: tls API for direct TLS socket use #10846

Closed

child_process.fork: add string-shortcut for stdio #10866

Closed

thefourtheye reviewed Jan 28, 2017

View reviewed changes

Trott mentioned this pull request Jan 31, 2017

Node.js Foundation Core Technical Committee (CTC) Meeting 2017-02-01 nodejs/CTC#65

Closed

ChALkeR approved these changes Feb 1, 2017

View reviewed changes

ofrobots reviewed Feb 1, 2017

View reviewed changes

jasnell force-pushed the deprecation-cycle branch from a0e97a6 to dc9e99d Compare February 1, 2017 17:33

nodejs-github-bot removed lts-watch-v6.x labels Feb 1, 2017

meta: add explicit deprecation and semver-major policy

305a354

* 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 February 1, 2017 17:36

sam-github approved these changes Feb 1, 2017

View reviewed changes

jasnell closed this Feb 1, 2017

italoacasas mentioned this pull request Feb 5, 2017

Proposal - 7.6.0 (Current) #11185

Merged

ChALkeR mentioned this pull request Feb 8, 2017

Changing Definition of "Locked" for Stability Index in API Docs #11200

Closed

Trott removed the ctc-agenda label Feb 9, 2017

ChALkeR mentioned this pull request Feb 14, 2017

WHATWG URL API is marked as Experimental, but is not behind a flag #11362

Closed

MylesBorins mentioned this pull request Mar 9, 2017

v6.10.1 proposal #11759

Merged

MylesBorins mentioned this pull request Mar 9, 2017

v4.8.1 proposal #11760

Merged

Trott mentioned this pull request May 13, 2017

fs: Revert throw on invalid callbacks #12976

Merged

meta: deprecation policy by jasnell · Pull Request #7964 · nodejs/node · GitHub

Uh oh!

Uh oh!

meta: deprecation policy - #7964

meta: deprecation policy#7964jasnell wants to merge 1 commit intonodejs:masternodejs/node:masterfrom jasnell:deprecation-cyclejasnell/node:deprecation-cycleCopy head branch name to clipboard

Conversation

jasnell commented Aug 3, 2016

Checklist

Affected core subsystem(s)

Description of change

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Trott commented Aug 3, 2016

Uh oh!

jasnell commented Aug 3, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Aug 4, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ChALkeR left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasnell commented Feb 1, 2017

Uh oh!

jasnell commented Feb 1, 2017

Uh oh!

jasnell commented Feb 1, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

17 participants

meta: deprecation policy#7964
jasnell wants to merge 1 commit into
nodejs:masterfrom
jasnell:deprecation-cycle