doc: add full deprecation history #22766

tniessen · 2018-09-09T00:08:52Z

I've had a hard time working with the deprecation documentation since it is currently lacking a history. Finding out when a deprecation was introduced or changed is difficult via Git and often impossible using our documentation alone. I think it is crucial to make the deprecation history transparent to users, so I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier for users to find out when deprecations were introduced or changed, and it also helps us in maintaining Node.js.

The diff itself is large but will be low-maintenance once we start properly documenting these things. I also had to slightly fix the documentation tool to accept multiple versions for a single change. Note that some ancient versions might be slightly imprecise, tracking down deprecations from pre-io.js releases turned out to be difficult from time to time.

(This partially reverts #21498 in that it adds the removed documentation sections again and updates them to properly represent the history of these deprecations.)

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash.

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed.

nodejs-github-bot · 2018-09-09T00:08:53Z

@tniessen build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/836/pipeline

devsnek

impressive work 👍

cjihrig

Mostly rubberstamp LGTM.

vsemozhetbyt

With nits)

Thank you for the heavy lifting.

doc/api/deprecations.md

vsemozhetbyt · 2018-09-09T21:14:44Z

doc/api/deprecations.md

@@ -865,6 +1838,12 @@ Type: Runtime

 <a id="DEP0097"></a>
 ### DEP0097: MakeCallback with domain property
+<!--


Missing YAML.

doc/api/deprecations.md

vsemozhetbyt · 2018-09-09T23:11:33Z

doc/api/deprecations.md

+    pr-url: https://github.com/nodejs/node/pull/10116
+    description: A deprecation code has been assigned.
+  - version:
+    pr-url:


tniessen · 2018-09-10T12:36:44Z

Thanks for reviewing so thoroughly, @vsemozhetbyt!

tniessen · 2018-09-11T14:55:02Z

CI: https://ci.nodejs.org/job/node-test-pull-request-lite/929/
Resumed in: https://ci.nodejs.org/job/node-test-pull-request-lite/930/

BridgeAR

Great work

BridgeAR · 2018-09-09T21:51:13Z

doc/api/deprecations.md

+changes:
+  - version: v10.0.0
+    pr-url: https://github.com/nodejs/node/pull/19524
+    description: Runtime deprecation.


Nit: partial runtime deprecation.

Oh, sorry, must have missed the comment before landing :/ "partial" as in "not all occurrences will warn" or as in "only some variants of the constructor will warn"?

Not all occurrences will warn (ones that are in an npm module).

Okay, mhhh I guess that's currently clear from the description, but it might be less obvious if that ever changes...

It should be fine. When deprecating it more it could be changed accordingly.

tniessen · 2018-09-12T09:47:56Z

Landed in 1f5261b, ed130d2.

Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash. PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed. PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash. PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

targos · 2018-09-12T19:49:13Z

It would be awesome to have this in v10.x's documentation. A backport PR will be needed for that.

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed. PR-URL: nodejs#22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

tniessen · 2018-09-12T20:09:14Z

@targos #22826

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed. Backport-PR-URL: #22826 PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash. PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed. Backport-PR-URL: #22826 PR-URL: #22766 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: James M Snell <jasnell@gmail.com>

tniessen added 2 commits September 9, 2018 01:48

tools: fix doc tool behavior for version arrays

2223cac

Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash.

doc: add full deprecation history

31db45f

I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed.

tniessen requested a review from vsemozhetbyt September 9, 2018 00:08

nodejs-github-bot added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels Sep 9, 2018

tniessen added the deprecations Issues and PRs related to deprecations. label Sep 9, 2018

fixup! tools: fix doc tool behavior for version arrays

4af8bf7

devsnek approved these changes Sep 9, 2018

View reviewed changes

cjihrig approved these changes Sep 9, 2018

View reviewed changes

vsemozhetbyt approved these changes Sep 9, 2018

View reviewed changes

fixup! doc: add full deprecation history

9fc6944

vsemozhetbyt reviewed Sep 9, 2018

View reviewed changes

doc/api/deprecations.md Show resolved Hide resolved

vsemozhetbyt reviewed Sep 9, 2018

View reviewed changes

tniessen assigned tniessen and unassigned tniessen Sep 10, 2018

fixup! doc: add full deprecation history

61967a8

jasnell approved these changes Sep 10, 2018

View reviewed changes

BridgeAR approved these changes Sep 11, 2018

View reviewed changes

tniessen closed this Sep 12, 2018

targos added the backport-requested-v10.x label Sep 12, 2018

tniessen mentioned this pull request Sep 12, 2018

(v10.x backport) doc: add full deprecation history #22826

Closed

targos added backported-to-v10.x and removed backport-requested-v10.x labels Sep 15, 2018

targos mentioned this pull request Sep 18, 2018

Release proposal: v10.11.0 #22932

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add full deprecation history #22766

doc: add full deprecation history #22766

tniessen commented Sep 9, 2018

nodejs-github-bot commented Sep 9, 2018

devsnek left a comment

cjihrig left a comment

vsemozhetbyt left a comment

vsemozhetbyt Sep 9, 2018 •

edited

Loading

vsemozhetbyt Sep 9, 2018

tniessen commented Sep 10, 2018

tniessen commented Sep 11, 2018 •

edited

Loading

BridgeAR left a comment

BridgeAR Sep 9, 2018

tniessen Sep 12, 2018

BridgeAR Sep 12, 2018

tniessen Sep 12, 2018

BridgeAR Sep 12, 2018

tniessen commented Sep 12, 2018

targos commented Sep 12, 2018

tniessen commented Sep 12, 2018

doc: add full deprecation history #22766

doc: add full deprecation history #22766

Conversation

tniessen commented Sep 9, 2018

Checklist

nodejs-github-bot commented Sep 9, 2018

devsnek left a comment

Choose a reason for hiding this comment

cjihrig left a comment

Choose a reason for hiding this comment

vsemozhetbyt left a comment

Choose a reason for hiding this comment

vsemozhetbyt Sep 9, 2018 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt Sep 9, 2018

Choose a reason for hiding this comment

tniessen commented Sep 10, 2018

tniessen commented Sep 11, 2018 • edited Loading

BridgeAR left a comment

Choose a reason for hiding this comment

BridgeAR Sep 9, 2018

Choose a reason for hiding this comment

tniessen Sep 12, 2018

Choose a reason for hiding this comment

BridgeAR Sep 12, 2018

Choose a reason for hiding this comment

tniessen Sep 12, 2018

Choose a reason for hiding this comment

BridgeAR Sep 12, 2018

Choose a reason for hiding this comment

tniessen commented Sep 12, 2018

targos commented Sep 12, 2018

tniessen commented Sep 12, 2018

vsemozhetbyt Sep 9, 2018 •

edited

Loading

tniessen commented Sep 11, 2018 •

edited

Loading