docs do not state at what version an API was introduced (or deprecated) #6578

sam-github · 2016-05-04T22:06:49Z

node documentation just documents the current node, but to write portable node.js, its important to know about when APIs were introduced (or changed incompatibly)

I regularly find developers attempting to use features that only exist on the most recent Node.js versions, such as the v8 module, without realizing it doesn't exist on some LTS versions.

It would be quite helpful if the API docs were annotated with the version in which an API was introduced.

cc: @chrisdickinson @bhajian

(edited by @addaleax)

Now that basic tooling for this feature is available in the doctool, it would be nice to see if we can get some people together for looking up the versions in which features were added/deprecated! If you’d like to volunteer, I’d suggest you just comment on this issue.

Documentation files for which this is definitely worthwhile:

Docs for which this may or may not make sense:

The text was updated successfully, but these errors were encountered:

jasnell · 2016-05-04T22:20:59Z

See: #6495
/cc @addaleax

addaleax · 2016-05-04T22:34:03Z

Yep, I guess I can land that one now.

@sam-github If you don’t mind, I’d like to use this issue (edit your original comment) to keep a list of the doc files for which this work needs to be done and tag this good-first-contribution?

MylesBorins · 2016-05-04T23:51:36Z

that sounds like an excellent idea @addaleax

addaleax · 2016-05-05T00:09:52Z

@thealphanerd @sam-github @bengl Looking good to everybody? Is this something you can share via social media in this state? :)

bengl · 2016-05-05T00:17:00Z

tweeted: https://twitter.com/bengl/status/728016045110222848

Also, I'm unclear on this: some features were added in one version and then only documented in another. Which versions should the added field represent?

addaleax · 2016-05-05T00:26:39Z

@bengl The version in which it was added, not the one in which it was documented. :)

Module introduced in 7ff04c1. Ref: nodejs#6578

Via git spelunking, mostly. Some functions have been renamed. Used the version in which they were renamed. Ref: nodejs#6578

Derived from git history. Ref: nodejs#6578

sam-github · 2016-05-06T20:00:21Z

@addaleax I don't mind, I'm thrilled to see you can get this going.

https://nodejs.org/api/tls.html#tls_event_resumesession is one thing that's bit me before, it didn't used to have a callback... and now the callback is mandatory, its one of the few APIs that changed a lot, but not in a way that will cause your code to blow up... just quietly hang.

Most of the information is gleaned from changelogs. The rest is inferred from git history. Omitted cpuUsage() since it's not yet in a release. Also omitted the streams, events and signals, since I didn't really think it made sense for those. Ref: nodejs#6578

Module introduced in 7ff04c1. Ref: #6578 PR-URL: #6593 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Anna Henningsen <anna@addaleax.net>

Most of the information is gleaned from changelogs. The rest is inferred from git history. Omitted cpuUsage() since it's not yet in a release. Also omitted the streams, events and signals, since I didn't really think it made sense for those. Ref: #6578 PR-URL: #6589 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Alexander Makarenko <estliberitas@gmail.com>

Via git spelunking, mostly. Some functions have been renamed. Used the version in which they were renamed. Ref: #6578 PR-URL: #6609 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Ref: nodejs#6578

lpinca · 2016-09-12T06:24:03Z

Should we also add this information for

addons.md
debugger.md
domain.md
globals.md

or can this issue be closed?

addaleax · 2016-09-13T12:45:19Z

globals.md

Maybe, if anyone’s up for that. Everything in there is ancient, so it shouldn’t make a huge difference…

italoacasas · 2016-09-13T13:41:19Z

I'll take globals.md @addaleax

Since I was doing the necessary git archaeology anyway, I took the time to add YAML information to the docs about when `addMembership()` and `dropMembership()` first appeared in their current forms. PR-URL: #6753 Ref: #6578 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>

Ref: nodejs#6578 PR-URL: nodejs#7640 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

Ref: #6578 PR-URL: #7640 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

lpinca · 2016-10-02T17:39:28Z

@italoacasas are you still up for globals.md?

italoacasas · 2016-10-02T19:03:27Z

@lpinca I forgot about this completely, I'm a little busy right now with some tests, but I'm going to tackle this down in a week if no one does first.

lpinca · 2016-10-02T19:07:15Z

@italoacasas sure, just let me know if you don't have the time. I would really like to see this completed.

italoacasas · 2016-10-02T19:13:11Z

@lpinca well If someone else wants to make globals.md update, feel free, please. I don't want to stop anyone contribution.

If when I finish the stream tests, globals.md still undone, I will do the update.

Ref: #6578 PR-URL: #8901 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

Ref: nodejs#6578 PR-URL: nodejs#8901 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>

Ref: #6578 Ref: #8964 PR-URL: #8901 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: Anna Henningsen <anna@addaleax.net>