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.

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

meta: deprecation policy #7964

Closed
wants to merge 1 commit into from
Closed

Conversation

jasnell
Copy link
Member

@jasnell jasnell commented Aug 3, 2016

Checklist
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

meta

Description of change

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

@jasnell jasnell added the meta Issues and PRs related to the general management of the project. label Aug 3, 2016
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 3, 2016
@@ -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
Copy link
Member

Choose a reason for hiding this comment

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

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
Copy link
Member

Trott commented Aug 3, 2016

Tons of nits, but no major objections. LGTM.

@jasnell
Copy link
Member Author

jasnell commented Aug 3, 2016

Updated!

* 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.
Copy link
Member

Choose a reason for hiding this comment

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

missing closing *?

Copy link
Member Author

Choose a reason for hiding this comment

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

Fixed!

@jasnell
Copy link
Member Author

jasnell commented Aug 4, 2016

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
Copy link
Contributor

Choose a reason for hiding this comment

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

Shouldn't we remove APIs at this level?

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Member Author

Choose a reason for hiding this comment

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

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.

Copy link
Member

@ChALkeR ChALkeR left a comment

Choose a reason for hiding this comment

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

LGTM, this is great.

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
Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

Choose a reason for hiding this comment

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

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
Copy link
Member Author

jasnell commented Feb 1, 2017

@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
Copy link
Member Author

jasnell commented Feb 1, 2017

Given the reviews, I believe this is ready to go ahead and land.

jasnell added a commit that referenced this pull request Feb 1, 2017
* 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]>
@jasnell
Copy link
Member Author

jasnell commented Feb 1, 2017

Landed in e5bd880

@jasnell jasnell closed this Feb 1, 2017
italoacasas pushed a commit to italoacasas/node that referenced this pull request Feb 2, 2017
* 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]>
@Trott Trott removed the ctc-agenda label Feb 9, 2017
italoacasas pushed a commit to italoacasas/node that referenced this pull request Feb 14, 2017
* 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]>
jasnell added a commit that referenced this pull request Mar 7, 2017
* 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]>
jasnell added a commit that referenced this pull request Mar 7, 2017
* 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]>
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
* 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]>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
MylesBorins pushed a commit that referenced this pull request Mar 9, 2017
* 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]>
@MylesBorins MylesBorins mentioned this pull request Mar 9, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Development

Successfully merging this pull request may close these issues.