FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: list the stability status of each module by Lxxyx · Pull Request #36223 · nodejs/node · GitHub

/ node Public

doc: list the stability status of each module - #36223

Closed
Lxxyx wants to merge 6 commits into
nodejs:masterfrom
Lxxyx:master
ConversationCommits (6)ChecksFiles changed
Closed

doc: list the stability status of each module#36223
Lxxyx wants to merge 6 commits into
nodejs:masterfrom
Lxxyx:master

Conversation

Lxxyx commented Nov 22, 2020 •
edited
Loading

Copy link
Copy Markdown
Member

Fixes: #23723

Generate a module compatibility table from out/doc/all.json and insert it into documentation.html/md/json.

Preview:

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

nodejs-github-bot added build Issues and PRs related to build files or the CI. doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels Nov 22, 2020

mscdex commented Nov 22, 2020

Copy link
Copy Markdown
Contributor

I'm not sure something like this is that useful for at least a couple of reasons:

  • Users have to know to specifically navigate to the "about this documentation" to see it/know about it. If anything, something like this should probably live in the left sidebar so it's immediately visible, perhaps as a colored icon next to each category name?

  • Ultimately assigning a stability to each category is misleading/confusing. What does the stability cover? The existence of the module itself? The entirety of the APIs that live under that category? Something else? For example, the Buffer category is shown here as "Stable", however the category contains several deprecated APIs. Even once we figure out what it should be representing, how do we communicate that clearly and easily to the end user (and is this information particularly useful)?

Lxxyx commented Nov 22, 2020

Copy link
Copy Markdown
Member Author

@mscdex Thank you for your feedback.

  1. In the previous issues doc: list the stability status of each API in one place? #23723 (comment), it was decided to put the stability table on the "About this documentation" page. And the stability table helps the developer to choose the right module when using Node.js

  2. What is shown here is the stability of the modules. We are not creating a new semantics, just showing it.

  3. As for Buffer, the Buffer module has some deprecated methods, but the module is stable (many modules have a similar situation).

joyeecheung approved these changes Nov 23, 2020
View reviewed changes

joyeecheung left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

LGTM, though @mscdex 's idea of adding icons to the sidebar to indicate stability also sounds good. Any thoughts? @nodejs/documentation

gireeshpunathil commented Nov 23, 2020

Copy link
Copy Markdown
Member

some improvements possible (splitting the exact API that is non-stable into separate rows etc) , but thinking more about , it may be difficult to maintain - this is simple and useful as is.

MylesBorins commented Nov 23, 2020

Copy link
Copy Markdown
Contributor

It looks like Modules is not fully covered. There are a variety of APIs that have stability levels including

  • commonjs modules
  • ES Modules
  • various package.json based features (e.g. package exports)
  • the module API

I think this goes back to @cjihrig's comment that this isn't entirely accurate for all cases as some modules have methods that are deprecated or experimental.

There is also an inconsistency here between the section title and the API name. fs is in lower case but HTTP is all caps (the module is http). I'd like to see a bit more consistency here.

To be clear, this is great work and I'm mostly pointing out edgecases. I won't block, but it would be nice to see some of these cases worked through

Lxxyx force-pushed the master branch 2 times, most recently from e1937d8 to bd75e2c Compare November 24, 2020 03:16

Lxxyx commented Nov 24, 2020

Copy link
Copy Markdown
Member Author

@MylesBorins Thank you for your feedback.

I updated the code so that the section title and API name are now identical and in lowercase.

Preview:

Trott approved these changes Nov 24, 2020
View reviewed changes

Trott left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

While there will always be ways to improve it and I don't want to discourage those improvements, this is an improvement as it stands and so I'd be fine with landing it, especially since the table is maintained programmatically and so should not be a maintenance annoyance that gets out of synch with other docs.

MylesBorins approved these changes Nov 24, 2020
View reviewed changes

MylesBorins left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

This is a great iterative improvement. Definitely places to improve, but that will drive more contributions to node!

LGTM

Trott commented Jan 8, 2021

Copy link
Copy Markdown
Member

dgram is showing up in an unexpected place in the table (because it's being ordered as udp I guess). Not a blocking comment. This can land. But if it's easy enough to fix, let's do that.

Lxxyx commented Jan 8, 2021

Copy link
Copy Markdown
Member Author

dgram is showing up in an unexpected place in the table (because it's being ordered as udp I guess). Not a blocking comment. This can land. But if it's easy enough to fix, let's do that.

Thanks for the reply, the problem has been fixed.

Preview

aduh95 reviewed Jan 18, 2021
View reviewed changes
Comment thread Makefile
Comment thread tools/doc/stability.js Outdated
Lxxyx and others added 2 commits January 19, 2021 12:26
Update Makefile
70979d2 
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Update tools/doc/stability.js
32d333c 
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
aduh95 reviewed Jan 19, 2021
View reviewed changes

aduh95 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Apologies, my suggestion was flawed – we need to specify the position, otherwise it sometimes jump to the end of the file.

Comment thread tools/doc/stability.js Outdated
Comment thread tools/doc/stability.js Outdated
Lxxyx and others added 2 commits January 19, 2021 19:13
Update tools/doc/stability.js
579c21c 
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Update tools/doc/stability.js
8c573d1 
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
aduh95 reviewed Jan 19, 2021
View reviewed changes
Comment thread tools/doc/stability.js Outdated
Update tools/doc/stability.js
f0103c6 
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
aduh95 added the author ready PRs that have at least one approval, no outstanding review comments, and a CI started. label Jan 19, 2021

nodejs-github-bot commented Jan 19, 2021

Copy link
Copy Markdown
Collaborator

CI: https://ci.nodejs.org/job/node-test-pull-request/35637/

aduh95 commented Jan 20, 2021

Copy link
Copy Markdown
Contributor

Landed in 2bb42bf

aduh95 closed this Jan 20, 2021
aduh95 pushed a commit that referenced this pull request Jan 20, 2021
tools,doc: list the stability status of each API
2bb42bf 
Fixes: #23723

PR-URL: #36223
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
ruyadorno pushed a commit that referenced this pull request Jan 22, 2021
tools,doc: list the stability status of each API
4cd471e 
Fixes: #23723

PR-URL: #36223
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
ruyadorno mentioned this pull request Jan 22, 2021
Merged
ruyadorno pushed a commit that referenced this pull request Jan 25, 2021
tools,doc: list the stability status of each API
17bdcd9 
Fixes: #23723

PR-URL: #36223
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
richardlau mentioned this pull request Apr 2, 2021
Closed
targos pushed a commit that referenced this pull request May 1, 2021
tools,doc: list the stability status of each API
15d66fb 
Fixes: #23723

PR-URL: #36223
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
danielleadams mentioned this pull request May 3, 2021
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Show hidden characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

jasnell jasnell approved these changes
Trott Trott approved these changes
joyeecheung joyeecheung approved these changes
gireeshpunathil gireeshpunathil approved these changes
aduh95 aduh95 approved these changes
+3 more reviewers
fhinkel fhinkel approved these changes
MylesBorins MylesBorins approved these changes
aymen94 aymen94 approved these changes
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

author ready PRs that have at least one approval, no outstanding review comments, and a CI started. build Issues and PRs related to build files or the CI. doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

doc: list the stability status of each API in one place?
Back | FazBrowse Home | New Git URL