doc: deprecation clarifications #19522

jasnell · 2018-03-21T19:44:44Z

Clarify some details on the deprecation policy. Specifically:

Clarify that deprecated code is not subject to the typical support (current or LTS) policies
Clarify that deprecation does not automatically mean removal. Code may be docs-deprecated or runtime deprecated indefinitely.
Clarify that End-of-Life does not necessarily mean removal. What it means is that changes are no longer subject to the semver rules, up to and including removal.

Checklist

documentation is changed or added
commit message follows commit guidelines

targos · 2018-03-21T19:52:14Z

COLLABORATOR_GUIDE.md

-  Documentation-only deprecations may trigger a runtime warning when launched
-  with [`--pending-deprecation`][] flag (or its alternative,
-  `NODE_PENDING_DEPRECATION=1` environment variable).
+  Documentation-only deprecations may trigger an opt-in only runtime warning


I'm not sure "opt-in only" is necessary

an opt-in only runtime warning -> a runtime warning

targos · 2018-03-21T19:53:34Z

COLLABORATOR_GUIDE.md

@@ -427,7 +428,9 @@ Node.js uses three Deprecation levels:
  deprecated status.

 * *End-of-life* refers to APIs that have gone through Runtime Deprecation and
-  are ready to be removed from Node.js entirely.
+  are no longer subject to the semantic-versioning and support policies used by


"semantic versioning" without dash

Can we link to these policies here?

Trott · 2018-03-21T20:20:56Z

COLLABORATOR_GUIDE.md

+__Deprecation__ refers to the identification of Public APIs that should no
+longer be used.
+
+Once specific bits of code are marked as being Deprecated, they are no longer


specific bits of code are marked as being Deprecated -> APIs are deprecated

Trott · 2018-03-21T20:21:40Z

COLLABORATOR_GUIDE.md

+longer be used.
+
+Once specific bits of code are marked as being Deprecated, they are no longer
+covered by the typical current or Long Term Support policies.


Remove typical or current. More importantly, what does this mean? Is this all about semver or is it something else?

For instance, a deprecated function in an LTS branch would not fall under the same scrutiny and care as a non-deprecated function in that same branch, meaning we may be more liberal about what changes we allow to be made within those

Can we link to these policies here?

Trott · 2018-03-21T20:23:46Z

COLLABORATOR_GUIDE.md

-  `NODE_PENDING_DEPRECATION=1` environment variable).
+  Documentation-only deprecations may trigger an opt-in only runtime warning
+  when Node.js is launched with the [`--pending-deprecation`][] flag (or its
+  alternative, `NODE_PENDING_DEPRECATION=1` environment variable).


(or its alternative, `NODE_PENDING_DEPRECATION=1` environment variable) -> or if the `NODE_PENDING_DEPRECATION` environment variable is set.

the value specifically needs to be NODE_PENDING_DEPRECATION=1

Trott · 2018-03-21T20:24:48Z

COLLABORATOR_GUIDE.md

@@ -427,7 +428,9 @@ Node.js uses three Deprecation levels:
  deprecated status.

 * *End-of-life* refers to APIs that have gone through Runtime Deprecation and
-  are ready to be removed from Node.js entirely.
+  are no longer subject to the semantic-versioning and support policies used by
+  the project. Backward-incompatible changes or even complete removal of such


or even -> including

Trott · 2018-03-21T20:24:59Z

COLLABORATOR_GUIDE.md

-  are ready to be removed from Node.js entirely.
+  are no longer subject to the semantic-versioning and support policies used by
+  the project. Backward-incompatible changes or even complete removal of such
+  code may occur at any time.


code -> APIs

Trott · 2018-03-21T20:25:43Z

COLLABORATOR_GUIDE.md

+Runtime Deprecation cycle. However, there is no requirement that deprecated
+code must progress ultimately to *End-of-Life*. It is possible, and at times
+preferable, for code that is documentation-only or runtime deprecated to
+remain so indefinitely.


It is possible, and at times preferable, for code that is documentation-only or runtime deprecated to remain so indefinitely. -> Documentation-only and runtime deprecations may remain indefinitely.

Trott

Fine in concept, just making sure this doesn't land without some of the requested changes...

Trott · 2018-03-22T21:49:11Z

COLLABORATOR_GUIDE.md

+longer be used.
+
+Once APIs are Deprecated, they are no longer covered by the current or
+[Long Term Support][LTS] policies.


That's a link to a repository that doesn't seem to have any policies. Honest, I'm not sure what this sentence means. If it's only about the fact that breaking changes can happen with deprecated APIs, then that's covered later in this doc and much more clearly than here. If it's about something else...what is it?

(I think you can remove this sentence entirely TBQH.)

Trott · 2018-03-22T21:49:46Z

COLLABORATOR_GUIDE.md

-  Documentation-only deprecations may trigger a runtime warning when launched
-  with [`--pending-deprecation`][] flag (or its alternative,
-  `NODE_PENDING_DEPRECATION=1` environment variable).
+  Documentation-only deprecations may trigger an runtime warning when Node.js


an runtime -> a runtime

Trott · 2018-03-22T21:50:10Z

COLLABORATOR_GUIDE.md

-  with [`--pending-deprecation`][] flag (or its alternative,
-  `NODE_PENDING_DEPRECATION=1` environment variable).
+  Documentation-only deprecations may trigger an runtime warning when Node.js
+  is launched with the [`--pending-deprecation`][] flag, or the


launched -> started

remove comma after flag

Trott · 2018-03-22T21:51:56Z

COLLABORATOR_GUIDE.md

@@ -427,7 +428,9 @@ Node.js uses three Deprecation levels:
  deprecated status.

 * *End-of-life* refers to APIs that have gone through Runtime Deprecation and
-  are ready to be removed from Node.js entirely.
+  are no longer subject to the semantic versioning and [support policies](LTS)


As above, the link here doesn't provide clarity. Can you be specific about some aspect of deprecated APIs that is different than everything else other than the semantic version stuff? If not, let's remove and support policies.

Trott

Thanks for your patience with all the nits!

PR-URL: #19522 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>

jasnell · 2018-04-02T22:11:27Z

Landed in 7238b92

vsemozhetbyt · 2018-04-02T22:29:06Z

It seems this breaks doc linting: https://ci.nodejs.org/job/node-test-linter/17623/console

18:17:16 COLLABORATOR_GUIDE.md
18:17:16   411:1-411:16  warning  Strong should use `*` as a marker   strong-marker        remark-lint
18:17:16         434:82  warning  Line must be at most 80 characters  maximum-line-length  remark-lint
18:17:16 
18:17:16 ⚠ 2 warnings

vsemozhetbyt · 2018-04-02T22:54:59Z

#19762 :)

Trott · 2018-04-02T22:55:36Z

It looks like this was landed without running through CI at all.

Trott · 2018-04-02T23:20:02Z

(I'm sure this happens a lot, but since I'm noticing it because I'm looking at this: The commit message also does not conform to guidelines. First word should be an imperative verb, such as clarify as in doc: clarify deprecations.)

vsemozhetbyt · 2018-04-02T23:26:09Z

Mighty spring)

jasnell · 2018-04-03T00:58:05Z

Hmm... Something must be out of sync locally on my end then because linting passed locally. Will open a fix PR a bit later this evening

jasnell · 2018-04-03T00:59:02Z

Nevermind! Just saw it was already done 😁 thank you kindly!

Trott · 2018-04-03T01:34:23Z

Hmm... Something must be out of sync locally on my end then because linting passed locally.

@jasnell I believe there is currently a gotcha where make lint will skip linting the docs if the markdown linter isn't installed. On CI, it always gets installed (I think with make lint-md-build before make lint is run.

PR-URL: #19522 Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>

doc: deprecation clarifications

11c3a41

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Mar 21, 2018

BridgeAR approved these changes Mar 21, 2018

View reviewed changes

targos approved these changes Mar 21, 2018

View reviewed changes

Trott reviewed Mar 21, 2018

View reviewed changes

gireeshpunathil approved these changes Mar 22, 2018

View reviewed changes

Trott requested changes Mar 22, 2018

View reviewed changes

[Squash] address feedback

cb84aaa

Trott reviewed Mar 22, 2018

View reviewed changes

[Squash] nits

4c9c281

targos approved these changes Mar 24, 2018

View reviewed changes

Trott approved these changes Mar 24, 2018

View reviewed changes

gibfahn approved these changes Mar 26, 2018

View reviewed changes

jasnell closed this Apr 2, 2018

targos mentioned this pull request Apr 4, 2018

v9.11.0 proposal #19799

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: deprecation clarifications #19522

doc: deprecation clarifications #19522

jasnell commented Mar 21, 2018

targos Mar 21, 2018

Trott Mar 21, 2018

targos Mar 21, 2018

Trott Mar 21, 2018

Trott Mar 21, 2018 •

edited

Loading

Trott Mar 21, 2018 •

edited

Loading

jasnell Mar 21, 2018

Trott Mar 21, 2018

Trott Mar 21, 2018 •

edited

Loading

jasnell Mar 22, 2018

Trott Mar 21, 2018

Trott Mar 21, 2018

Trott Mar 21, 2018

Trott left a comment

Trott Mar 22, 2018

Trott Mar 22, 2018

Trott Mar 22, 2018

Trott Mar 22, 2018

Trott Mar 22, 2018

Trott left a comment

jasnell commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

Trott commented Apr 2, 2018

Trott commented Apr 2, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018

jasnell commented Apr 3, 2018

jasnell commented Apr 3, 2018

Trott commented Apr 3, 2018 •

edited

Loading

doc: deprecation clarifications #19522

doc: deprecation clarifications #19522

Conversation

jasnell commented Mar 21, 2018

Checklist

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

Trott Mar 21, 2018 • edited Loading

Choose a reason for hiding this comment

Trott Mar 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott Mar 21, 2018 • edited Loading

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

Choose a reason for hiding this comment

Trott left a comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott left a comment

Choose a reason for hiding this comment

jasnell commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018

vsemozhetbyt commented Apr 2, 2018 • edited Loading

Trott commented Apr 2, 2018

Trott commented Apr 2, 2018 • edited Loading

vsemozhetbyt commented Apr 2, 2018

jasnell commented Apr 3, 2018

jasnell commented Apr 3, 2018

Trott commented Apr 3, 2018 • edited Loading

Trott Mar 21, 2018 •

edited

Loading

Trott Mar 21, 2018 •

edited

Loading

Trott Mar 21, 2018 •

edited

Loading

vsemozhetbyt commented Apr 2, 2018 •

edited

Loading

Trott commented Apr 2, 2018 •

edited

Loading

Trott commented Apr 3, 2018 •

edited

Loading