-
Notifications
You must be signed in to change notification settings - Fork 29k
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
doc: add full deprecation history #22766
Conversation
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
impressive work 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Mostly rubberstamp LGTM.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With nits)
Thank you for the heavy lifting.
doc/api/deprecations.md
Outdated
@@ -865,6 +1838,12 @@ Type: Runtime | |||
|
|||
<a id="DEP0097"></a> | |||
### DEP0097: MakeCallback with domain property | |||
<!-- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing YAML
.
doc/api/deprecations.md
Outdated
pr-url: https://github.com/nodejs/node/pull/10116 | ||
description: A deprecation code has been assigned. | ||
- version: | ||
pr-url: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ditto.
Thanks for reviewing so thoroughly, @vsemozhetbyt! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great work
changes: | ||
- version: v10.0.0 | ||
pr-url: https://github.com/nodejs/node/pull/19524 | ||
description: Runtime deprecation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: partial runtime deprecation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not all occurrences will warn (ones that are in an npm module).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Okay, mhhh I guess that's currently clear from the description, but it might be less obvious if that ever changes...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It should be fine. When deprecating it more it could be changed accordingly.
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 |
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>
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>
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>
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), orvcbuild test
(Windows) passes