Node: docs do not state at what version an API was introduced (or deprecated)

[sam-github]

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:

• [x] assert.md – @Trott in f52b2f116bf510e2af8750061ac6f8a0c9caa653 (#6688)
• [x] buffer.md – @addaleax in 4dcc692cada019cd2661ff807d829493ebf71594 (#6495)
• [x] child_process.md – @addaleax in 27d2267066add18a1eafa2ac852ffdb4ae3198be (#6927)
• [x] cli.md – @Trott in 90675818eede96a063489109f86022dd13ad75cb (#6960)
• [x] cluster.md – @addaleax in c628982a06e479f0d7d943c13131108924873ba4 (#7640)
• [x] console.md – @edsadr in 51b8a79bd46a28c2f576a579f258c2222e1a951b (#6995)
• [x] crypto.md – @lpinca in cfe8278328d190279532ab9b7fd13ae1bfd78ee2 (#8281)
• [x] dgram.md – @lpinca in 379d9162a2d992f7ff8a20d00f088ede1bf2f0fe (#8196)
• [x] dns.md – @julianduque in 71996506e9a979e73d20bd418a5c7e34a92c3f08 (#7021)
• [x] events.md – @lpinca in 769f63ccd8437045af5ddf1f418c53d2319597ed (#7822)
• [x] fs.md – @addaleax in ba10ea8f3af4a1af5c2f7df3e4f5af348f09e97b (#6717)
• [x] http.md – @addaleax in 72500f942b85e7fe66176b2807663aa225015e39 (#7392)
• [x] https.md – @addaleax in e8356b25cdf43079e8a6d74e02df67a49f64e471 (#7392)
• [x] modules.md – @lpinca in df4880de557fabafb625745c6ea75d3b755595d2 (#8250)
• [x] net.md – @italoacasas in 8bccc9e6c82c558132a28a462e9dd573ae0302c6 (#7038)
• [x] os.md – @bengl in 5a8c66a252c16b0d181fd7f1b3232941e5644971 (#6609)
• [x] path.md – @julianduque in bed44c94a0f05748fc5160610db33ed15f1f540c (#6985)
• [x] process.md – @bengl in ec67abe4a7c074bb66700c4aede56ffd4aaf3363 (#6589)
• [x] punycode.md – @firedfox in b90c52e38d47952bf6bef59d9a1c116b1972b8d9 (#6805)
• [x] querystring.md – @bengl in f7730733384cc15e8e5c842e3e1771e6f917c188 (#6593)
• [x] readline.md – @julianduque in 0ed4d8c535945865d48d50c023aba46f6286f616 (#6996)
• [x] repl.md – @addaleax in 740d8cf5e0bf85bbc756096ad40b44f19a4a4ddd (#7256)
• [x] stream.md – @italoacasas in c897d0ba71c0e73fbd37372e3dd4825e93cd251a (#7287)
• [x] string_decoder.md – @Trott in eb089e7ccd81c0951e4901df20f6dbaa084af143 (#6741)
• [x] tls.md – @italoacasas in c2e6078ed95cea135da8ebe4ef5a807e0bd0bbe2 (#7018)
• [x] tty.md – @trott in d3f3e183bfdd27a66ce4791ba0c933ab33a91512 (#6783)
• [x] url.md – @bengl in 43e4bafcaf1e40d62b4bbcd33ce8de946586e835 (#6593)
• [x] util.md – @lpinca in d9142b4bd6e48690337ac8f988719e67d7a361ce (#8206)
• [x] v8.md – @trott in b3bc36209f927bbdcdcada7e2170f91f1c32d1b3 (#6684)
• [x] vm.md – @addaleax in 16f98e589c69ffe6283aa11493fd417368708557 (#7011)
• [x] zlib.md – @addaleax in b49df8891682f0d429f7d594b9ab1185715eb4f7 (#6840)

Docs for which this may or may not make sense:

• [ ] addons.md
• [ ] debugger.md
• [ ] domain.md
• [ ] globals.md
• [x] timers.md – @addaleax in cd4dbf33481ee1432b0d71a6576492acc12b4298 (#7493)

[jasnell]

See: https://github.com/nodejs/node/pull/6495
/cc @addaleax

[addaleax]

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]

that sounds like an excellent idea @addaleax

[addaleax]

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

[bengl]

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]

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

[sam-github]

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

[Trott]

Minor issue, perhaps, but it's unclear to me how to maintain this going forward. Specifically, if I add a new API today, I add the docs material, and the YAML data...but what version do I put? 6.1.0 is the current version. So, 6.1.1. But what if the next version is actually 6.2.0? Do we care? Does someone have to go through and update everything? Am I overthinking it?

[addaleax]

You’re not overthinking. :D What @bengl did in ec67abe4a7c074bb66700c4aede56ffd4aaf3363 was to leave a TODO comment for process.cpuUsage, and I think that’s a reasonable approach as long as there are only so many features added in a single version.

It might be nice to hear some of @nodejs/release’s opinions on this, too.

[evanlucas]

What about something like Added: after 6.1.0 or Added: > 6.1.0?

[bnoordhuis]

One approach that could work is to leave placeholders in the documentation and add a pre-release check:

diff --git a/Makefile b/Makefile
index 8612055..6ea73bf 100644
--- a/Makefile
+++ b/Makefile
@@ -429,6 +429,10 @@ PACKAGEMAKER ?= /Developer/Applications/Utilities/PackageMaker.app/Contents/MacO
 PKGDIR=out/dist-osx

 release-only:
+       @if `grep -q REPLACEME doc/api/*.md`; then \
+               echo 'Please update Added: tags in the documentation first.' ; \
+               exit 1 ; \
+       fi
        @if [ "$(shell git status --porcelain | egrep -v '^\?\? ')" = "" ]; then \
                exit 0 ; \
        else \

[evanlucas]

I like that @bnoordhuis

[addaleax]

If the release folks are generally okay with that, I’d like that approach, too.

Alternatively, if that turns out to be too much work, one could do something like Added: __VERSION__ to the docs and apply the same replacement logic that is used for doc/template.html.

[Fishrock123]

I would consider doing this on release relatively trivial.

Generally though, we're missing something: Features will either land in a semver-minor, or wait for a major. So you'll virtually always be targeting the next minor release.

[cjihrig]

Seems like a fine idea to me.

[firedfox]

Just picked a small module punycode to start. I hope this helps.

[stevemao]

@nodejs/documentation

[Trott]

Working on cli.md right now and finding myself having to choose between when something was implemented vs. when it was documented.

I'm inclined to go with when it was documented as there's no guarantee that behavior didn't change between original implementation and eventual documentation.

This is all for stuff that was implemented and documented during v0.1.x (e.g., NODE_PATH) so I'm not sure it really matters much for 99+% of people who will be referencing the info, but want to get the principle straight in case it comes up elsewhere with more recent stuff.

[addaleax]

@Trott Well, sometimes behaviour also changes after things being documented.

So far, I’ve gone pretty much by when features were actually added rather than documented… Ultimately, something like little PHP-style per-feature changelogs would be pretty cool, and I’d like to push for implementing that once the main work over here is done. (I don’t consider it as important as added: info, but if you feel differently, please say so.)

And yes, I don’t think anything before v0.6 or so matters to anyone anymore, but it’s kinda cool having a rough overview of what happened when in the dark ages. :)

[lpinca]

Should we also add this information for

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

or can this issue be closed?

[addaleax]

globals.md

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

[italoacasas]

I'll take globals.md @addaleax

[lpinca]

@italoacasas are you still up for globals.md?

[italoacasas]

@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]

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

[italoacasas]

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

[targos]

@sam-github is this fully resolved?

[addaleax]

I think this can be closed now, yes.