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

joyeecheung · 2018-10-17T23:50:20Z

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

robertoschiavone · 2018-10-18T15:54:16Z

I can pick this one

hyeonQ · 2018-10-19T07:11:35Z

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

vsemozhetbyt · 2018-10-19T07:47:45Z

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 · 2018-10-19T08:49:24Z

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 · 2018-10-19T10:31:46Z

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

I think we have at least two options:

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?).
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 · 2018-10-19T11:16:30Z

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 · 2018-10-20T11:29:25Z

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 · 2018-10-26T01:47:03Z

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

shobhitchittora · 2018-10-30T18:03:41Z

@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 · 2019-01-05T19:13:17Z

can i take this issue

shuhei · 2019-02-02T20:17:51Z

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:

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
Insert the table into out/doc/api/documentations.md, .html and .json with the tool
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 · 2019-02-17T07:22:11Z

@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 · 2019-04-23T09:36:02Z

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

martin-dimitrov13 · 2019-05-14T10:48:40Z

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 · 2019-10-04T00:18:51Z

Hi, can I take this issue?

davalapar · 2019-12-03T21:46:32Z

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

manisaiprasad · 2020-01-16T20:00:09Z

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

shobhitchittora · 2020-01-17T07:14:50Z

@manisaiprasad You can give it a try.

HassanRazaMuhammadTufail · 2020-04-17T14:23:48Z

@shobhitchittora can I try this one?

mayankagarwals · 2020-10-30T15:31:21Z

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 · 2020-11-03T21:48:19Z

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 · 2020-11-04T06:07:36Z

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 · 2020-11-22T08:26:06Z

I'm working on this issue.

Fixes: nodejs#23723

Fixes: #23723 PR-URL: #36223 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Franziska Hinkelmann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

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

Trott added the Hacktoberfest label Sep 30, 2019

Trott removed the Hacktoberfest label Nov 3, 2019

This comment has been minimized.

Sign in to view

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

Lxxyx mentioned this issue Nov 22, 2020

doc: list the stability status of each module #36223

Closed

3 tasks

Lxxyx added a commit to Lxxyx/node that referenced this issue Dec 4, 2020

doc: list the stability status of each API

c41e94f

Fixes: nodejs#23723

Lxxyx added a commit to Lxxyx/node that referenced this issue Jan 8, 2021

doc: list the stability status of each API

5313444

Fixes: nodejs#23723

aduh95 closed this as completed in 2bb42bf Jan 20, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

joyeecheung commented Oct 17, 2018 •

edited

Loading

robertoschiavone commented Oct 18, 2018

hyeonQ commented Oct 19, 2018

vsemozhetbyt commented Oct 19, 2018 •

edited

Loading

joyeecheung commented Oct 19, 2018

vsemozhetbyt commented Oct 19, 2018 •

edited

Loading

rubys commented Oct 19, 2018 •

edited

Loading

hyeonQ commented Oct 20, 2018

huhgawz commented Oct 26, 2018 •

edited

Loading

shobhitchittora commented Oct 30, 2018

adarshsaraogi commented Jan 5, 2019

shuhei commented Feb 2, 2019

joyeecheung commented Feb 17, 2019 •

edited

Loading

RamirezAlex commented Apr 23, 2019

martin-dimitrov13 commented May 14, 2019 •

edited

Loading

jhonatantft commented Oct 4, 2019 •

edited

Loading

davalapar commented Dec 3, 2019

manisaiprasad commented Jan 16, 2020

shobhitchittora commented Jan 17, 2020

This comment has been minimized.

HassanRazaMuhammadTufail commented Apr 17, 2020

mayankagarwals commented Oct 30, 2020 •

edited

Loading

joyeecheung commented Nov 3, 2020

mayankagarwals commented Nov 4, 2020 •

edited

Loading

Lxxyx commented Nov 22, 2020

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

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

Comments

joyeecheung commented Oct 17, 2018 • edited Loading

robertoschiavone commented Oct 18, 2018

hyeonQ commented Oct 19, 2018

vsemozhetbyt commented Oct 19, 2018 • edited Loading

joyeecheung commented Oct 19, 2018

vsemozhetbyt commented Oct 19, 2018 • edited Loading

rubys commented Oct 19, 2018 • edited Loading

hyeonQ commented Oct 20, 2018

huhgawz commented Oct 26, 2018 • edited Loading

shobhitchittora commented Oct 30, 2018

adarshsaraogi commented Jan 5, 2019

shuhei commented Feb 2, 2019

joyeecheung commented Feb 17, 2019 • edited Loading

RamirezAlex commented Apr 23, 2019

martin-dimitrov13 commented May 14, 2019 • edited Loading

jhonatantft commented Oct 4, 2019 • edited Loading

davalapar commented Dec 3, 2019

manisaiprasad commented Jan 16, 2020

shobhitchittora commented Jan 17, 2020

This comment has been minimized.

HassanRazaMuhammadTufail commented Apr 17, 2020

mayankagarwals commented Oct 30, 2020 • edited Loading

joyeecheung commented Nov 3, 2020

mayankagarwals commented Nov 4, 2020 • edited Loading

Lxxyx commented Nov 22, 2020

joyeecheung commented Oct 17, 2018 •

edited

Loading

vsemozhetbyt commented Oct 19, 2018 •

edited

Loading

vsemozhetbyt commented Oct 19, 2018 •

edited

Loading

rubys commented Oct 19, 2018 •

edited

Loading

huhgawz commented Oct 26, 2018 •

edited

Loading

joyeecheung commented Feb 17, 2019 •

edited

Loading

martin-dimitrov13 commented May 14, 2019 •

edited

Loading

jhonatantft commented Oct 4, 2019 •

edited

Loading

mayankagarwals commented Oct 30, 2020 •

edited

Loading

mayankagarwals commented Nov 4, 2020 •

edited

Loading