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 API in one place? #23723

Closed
joyeecheung opened this issue Oct 17, 2018 · 24 comments
Closed

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

joyeecheung opened this issue Oct 17, 2018 · 24 comments
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors. help wanted Issues that need assistance from volunteers or PRs that need help to proceed.

Comments

@joyeecheung
Copy link
Member

joyeecheung commented Oct 17, 2018

Right now each API has their own page with their stability index, but AFAIK there is not a central place where you can find the stability status of all the APIs at a glance (correct me if I am wrong). It may be useful to have a list somewhere in https://github.com/nodejs/node/blob/master/doc/api/documentation.md#stability-index

@joyeecheung joyeecheung added doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors. labels Oct 17, 2018
@robertoschiavone
Copy link

I can pick this one

@hyeonQ
Copy link

hyeonQ commented Oct 19, 2018

I expect to make the first commit of nodejs. I can gather the stability of APIs in one place.

@vsemozhetbyt
Copy link
Contributor

vsemozhetbyt commented Oct 19, 2018

I suppose we may need to automate this with doc tools scripts. Otherwise, each deprecation and API addition will need to be addressed in this list manually which may be error-prone.

@joyeecheung
Copy link
Member Author

I suppose we may need to automate this with doc tools scripts.

@vsemozhetbyt Good idea. Can you leave a few pointers? I only have a vague idea that people who want to hack on this should start in https://github.com/nodejs/node/tree/master/tools/doc

Also cc @nodejs/documentation

@vsemozhetbyt
Copy link
Contributor

vsemozhetbyt commented Oct 19, 2018

Recently, we change our toolchain a bit, so maybe @rubys can give some hints.

I think we have at least two options:

  1. Parse TOC in all.html. TOC entries already have class="stability_*" attributes for deprecated and experimental stability. But we may need to distinguish API headers from other headers here (by a RegExp?).

  2. Parse all.json. It will be easier to distinguish API entries from other entries there (look for "classes", "methods", and "properties" fields), and the field "stability" also exists there.

@rubys
Copy link
Member

rubys commented Oct 19, 2018

I recommend that all.json approach. The input data is already parsed. Iterate over the structure, producing output as you go. The tool should go in the tools/doc/ directory, and added to the Makefile as depending on out/doc/api/all.json. As we seem to have volunteer(s), I'll review and coach as needed.

@hyeonQ
Copy link

hyeonQ commented Oct 20, 2018

I hope to try this work.
So far as I understand it, there is a need to gather the stability of the various APIs of node.js and It is a better to parse all.json.
By the way, I am confused which files need to be modified and where to put gathered things

@huhgawz
Copy link

huhgawz commented Oct 26, 2018

@HYU-LeeHG are you actively working on this issue? If not, it would be great to take it

@shobhitchittora
Copy link
Contributor

@rubys I went ahead wrote a script to get all the stability keys from the json mentioned.

API Stability
assert (2) Stable
async_hooks (1) Experimental
buffer (2) Stable
cluster (2) Stable
console (2) Stable
crypto (2) Stable
dns (2) Stable
dns_promises_api (1) Experimental
Events (2) Stable
fs (2) Stable
fs_promises_api (1) Experimental
http (2) Stable
http/2 (1) Experimental
https (2) Stable
inspector (1) Experimental
module (2) Stable
os (2) Stable
path (2) Stable
performance_timing_api (1) Experimental
querystring (2) Stable
readline (2) Stable
repl (2) Stable
stream (2) Stable
string_decoder (2) Stable
timers (2) Stable
tls_(ssl) (2) Stable
trace_events (1) Experimental
tty (2) Stable
dgram (2) Stable
url (2) Stable
util (2) Stable
serialization_api (1) Experimental
vm (2) Stable
vm.SourceTextModule (1) Experimental
worker_threads (1) Experimental
zlib (2) Stable

What are your thoughts on organizing this? What can be the next steps?

@adarshsaraogi
Copy link

can i take this issue

@shuhei
Copy link
Contributor

shuhei commented Feb 2, 2019

Hi, I was looking for a good first issue and ran into this issue.

So shobhitchittora@b0c5461 by @shobhitchittora already collects stability statuses and outputs them into a table. The problem is how to put it into the docs. Possible options would be:

  1. Output the table as a separate file like out/doc/api/stability_index.md (also .html and .json?) with the tool, and have a link to the file from doc/api/documentation.md
  2. Insert the table into out/doc/api/documentations.md, .html and .json with the tool
  3. Update doc/api/documentation.md with the tool and commit the change into git

The option 1 seems easiest to me. What do you think? @joyeecheung @rubys @shobhitchittora

@joyeecheung
Copy link
Member Author

joyeecheung commented Feb 17, 2019

@shuhei I'd prefer we do option 2 if possible, but we could also implement option 1 first (in any cases I can imagine a stability.json hosted on our website being useful for consumers)

@RamirezAlex
Copy link
Contributor

If no one is working on it I can give it a try.

@martin-dimitrov13
Copy link

martin-dimitrov13 commented May 14, 2019

Would this include only the top level API's (as in @shobhitchittora 's suggestion above) or do we want to breakdown the module + method stability as well?

I have a suggested solution which I will move into a PR soon.

My solution produces similar output to @shobhitchittora however it goes further to look for the Stability field for some APIs rather than just relying on a stability field always being present. It will always prefer the value in the stability first thou.

My question, however, is where would this script live in terms of a directory?

Here is an example on how the output would look like for the current latest version(node v12.2.0) :

API Stability
assert (2) Stable
async_hooks (1) Experimental
buffer (2) Stable
child_process (2) Stable
cluster (2) Stable
console (2) Stable
crypto (2) Stable
dns (2) Stable
domain (0) Deprecated
Events (2) Stable
fs (2) Stable
http (2) Stable
http/2 (2) Stable
https (2) Stable
inspector (1) Experimental
module (2) Stable
net (2) Stable
os (2) Stable
path (2) Stable
performance_timing_api (1) Experimental
punycode (0) Deprecated
querystring (2) Stable
readline (2) Stable
repl (2) Stable
stream (2) Stable
string_decoder (2) Stable
timers (2) Stable
tls_(ssl) (2) Stable
trace_events (1) Experimental
tty (2) Stable
dgram (2) Stable
url (2) Stable
util (2) Stable
v8 UNKNOWN
vm (2) Stable
worker_threads (1) Experimental
zlib (2) Stable

@jhonatantft
Copy link

jhonatantft commented Oct 4, 2019

Hi, can I take this issue?

@davalapar
Copy link

Awesome, I think the right place would be here at https://nodejs.org/api/documentation.html#documentation_stability_index

@manisaiprasad
Copy link

If no one is working on it
I can give it a try.

@shobhitchittora
Copy link
Contributor

@manisaiprasad You can give it a try.

1 similar comment
@shobhitchittora

This comment has been minimized.

@HassanRazaMuhammadTufail

@shobhitchittora can I try this one?

@jasnell jasnell added the help wanted Issues that need assistance from volunteers or PRs that need help to proceed. label Jun 26, 2020
@mayankagarwals
Copy link
Contributor

mayankagarwals commented Oct 30, 2020

Hey! First-time contributor here. Can I take this up if no one is working on it?
From what I understand from previous comments, @shobhitchittora has already created the tool to generate the table and all left is to insert this into the documentation?
Mentioning @jasnell here as he added the last label.

@joyeecheung
Copy link
Member Author

Hi @iammack

I think the best way to move forward would be to try opening a PR with the suggestions above. Adding the script to tools/doc and make sure it's run from tools/doc/generate.js to insert the table into documentation.md whenever someone generates the doc would be a good first step.

@mayankagarwals
Copy link
Contributor

mayankagarwals commented Nov 4, 2020

I agree. I think that @shobhitchittora and @martin-dimitrov13 already have branches with their solutions. If neither of you is continuing with it, I can proceed.

@Lxxyx
Copy link
Member

Lxxyx commented Nov 22, 2020

I'm working on this issue.

Lxxyx added a commit to Lxxyx/node that referenced this issue Dec 4, 2020
Lxxyx added a commit to Lxxyx/node that referenced this issue Jan 8, 2021
@aduh95 aduh95 closed this as completed in 2bb42bf Jan 20, 2021
ruyadorno pushed a commit that referenced this issue 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 pushed a commit that referenced this issue 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 issue 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. good first issue Issues that are suitable for first-time contributors. help wanted Issues that need assistance from volunteers or PRs that need help to proceed.
Projects
None yet
Development

Successfully merging a pull request may close this issue.