meta: deprecation policy #7964

jasnell · 2016-08-03T17:53:52Z

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

Trott · 2016-08-03T18:07:43Z

COLLABORATOR_GUIDE.md

@@ -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


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.

Trott · 2016-08-03T18:39:06Z

Tons of nits, but no major objections. LGTM.

jasnell · 2016-08-03T20:28:44Z

Updated!

addaleax · 2016-08-03T21:10:00Z

COLLABORATOR_GUIDE.md

+* 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.


missing closing *?

jasnell · 2016-08-04T18:25:42Z

fixed nits and added some additional discussion detail. PTAL

thefourtheye · 2017-01-28T07:36:20Z

COLLABORATOR_GUIDE.md

+  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


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.

ChALkeR

LGTM, this is great.

ofrobots · 2017-02-01T17:31:58Z

COLLABORATOR_GUIDE.md

+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


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

jasnell · 2017-02-01T17:43:14Z

@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.

jasnell · 2017-02-01T18:50:21Z

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>

jasnell · 2017-02-01T19:04:45Z

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

meta: deprecation policy #7964

meta: deprecation policy #7964

jasnell commented Aug 3, 2016

Trott Aug 3, 2016

Trott commented Aug 3, 2016

jasnell commented Aug 3, 2016

addaleax Aug 3, 2016

jasnell Aug 3, 2016

jasnell commented Aug 4, 2016

thefourtheye Jan 28, 2017

jasnell Jan 30, 2017

thefourtheye Jan 30, 2017

jasnell Jan 30, 2017

ChALkeR left a comment

ofrobots Feb 1, 2017

ofrobots Feb 1, 2017

jasnell commented Feb 1, 2017

jasnell commented Feb 1, 2017

jasnell commented Feb 1, 2017

meta: deprecation policy #7964

meta: deprecation policy #7964

Conversation

jasnell commented Aug 3, 2016

Checklist

Affected core subsystem(s)

Description of change

Choose a reason for hiding this comment

Trott commented Aug 3, 2016

jasnell commented Aug 3, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Aug 4, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChALkeR left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Feb 1, 2017

jasnell commented Feb 1, 2017

jasnell commented Feb 1, 2017