Skip to content
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: list the stability status of each module #36223

Closed
wants to merge 6 commits into from
Closed

Conversation

Lxxyx
Copy link
Member

@Lxxyx Lxxyx commented Nov 22, 2020

Fixes: #23723

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

Preview:
image

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

@nodejs-github-bot 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
Copy link
Contributor

mscdex commented Nov 22, 2020

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
Copy link
Member Author

Lxxyx commented Nov 22, 2020

@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).

Copy link
Member

@joyeecheung joyeecheung left a comment

Choose a reason for hiding this comment

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

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

@gireeshpunathil
Copy link
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
Copy link
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 Lxxyx force-pushed the master branch 2 times, most recently from e1937d8 to bd75e2c Compare November 24, 2020 03:16
@Lxxyx
Copy link
Member Author

Lxxyx commented Nov 24, 2020

@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:
image

Copy link
Member

@Trott Trott left a comment

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

@MylesBorins MylesBorins left a comment

Choose a reason for hiding this comment

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

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

LGTM

@Trott
Copy link
Member

Trott commented Jan 8, 2021

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
Copy link
Member Author

Lxxyx commented Jan 8, 2021

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

image

Makefile Show resolved Hide resolved
tools/doc/stability.js Outdated Show resolved Hide resolved
Lxxyx and others added 2 commits January 19, 2021 12:26
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Copy link
Contributor

@aduh95 aduh95 left a comment

Choose a reason for hiding this comment

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

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

tools/doc/stability.js Outdated Show resolved Hide resolved
tools/doc/stability.js Outdated Show resolved Hide resolved
Lxxyx and others added 2 commits January 19, 2021 19:13
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
tools/doc/stability.js Outdated Show resolved Hide resolved
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
@aduh95 aduh95 added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Jan 19, 2021
@nodejs-github-bot
Copy link
Collaborator

@aduh95
Copy link
Contributor

aduh95 commented Jan 20, 2021

Landed in 2bb42bf

@aduh95 aduh95 closed this Jan 20, 2021
aduh95 pushed a commit that referenced this pull request Jan 20, 2021
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
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 ruyadorno mentioned this pull request Jan 22, 2021
ruyadorno pushed a commit that referenced this pull request Jan 25, 2021
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>
targos pushed a commit that referenced this pull request May 1, 2021
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 danielleadams mentioned this pull request May 3, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, 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
Development

Successfully merging this pull request may close these issues.

doc: list the stability status of each API in one place?