doc: add full deprecation history by tniessen · Pull Request #22766 · nodejs/node · GitHub

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.

@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

impressive work 👍

Mostly rubberstamp LGTM.

With nits)

Thank you for the heavy lifting.

Missing YAML.

Ditto.

Thanks for reviewing so thoroughly, @vsemozhetbyt!

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/

Great work

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.

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>

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>

@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

Comment thread doc/api/deprecations.md Outdated

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

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

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

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

doc: add full deprecation history by tniessen · Pull Request #22766 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc: add full deprecation history - #22766

doc: add full deprecation history#22766tniessen wants to merge 5 commits intonodejs:masternodejs/node:masterfrom tniessen:doc-add-history-to-deprecationstniessen/node:doc-add-history-to-deprecationsCopy head branch name to clipboard

Conversation

tniessen commented Sep 9, 2018

Checklist

Uh oh!

nodejs-github-bot commented Sep 9, 2018

Uh oh!

devsnek left a comment

Choose a reason for hiding this comment

Uh oh!

cjihrig left a comment

Choose a reason for hiding this comment

Uh oh!

vsemozhetbyt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vsemozhetbyt Sep 9, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vsemozhetbyt Sep 9, 2018

Choose a reason for hiding this comment

Uh oh!

tniessen commented Sep 10, 2018

Uh oh!

tniessen commented Sep 11, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BridgeAR left a comment

Choose a reason for hiding this comment

Uh oh!

BridgeAR Sep 9, 2018

Choose a reason for hiding this comment

Uh oh!

tniessen Sep 12, 2018

Choose a reason for hiding this comment

Uh oh!

BridgeAR Sep 12, 2018

Choose a reason for hiding this comment

Uh oh!

tniessen Sep 12, 2018

Choose a reason for hiding this comment

Uh oh!

BridgeAR Sep 12, 2018

Choose a reason for hiding this comment

Uh oh!

tniessen commented Sep 12, 2018

Uh oh!

targos commented Sep 12, 2018

Uh oh!

tniessen commented Sep 12, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

doc: add full deprecation history#22766
tniessen wants to merge 5 commits into
nodejs:masterfrom
tniessen:doc-add-history-to-deprecations

vsemozhetbyt Sep 9, 2018 •
edited
Loading

tniessen commented Sep 11, 2018 •
edited
Loading