doc: add links to alternative versions of doc #10958

chris--young · 2017-01-23T04:46:31Z

Each page of the api documentation should have links to other versions
of the same page. This will make it easier to switch between the current
"live" release at nodejs.org and LTS versions.

Fixes: #10726

Checklist

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

Affected core subsystem(s)

doc, tools

evanlucas · 2017-01-23T12:05:03Z

This is great @chris--young. Thanks for doing this.

evanlucas · 2017-01-23T12:05:48Z

tools/doc/html.js

+  const a = (v) => `<a href="${href(v)}">v${v}</a>`;
+  const as = (vs) => vs.filter(lte).map(a).join(' / ');
+
+  const lts = as(['0.12.x', '4.x', '6.x']);


0.12 is no longer in maintenance mode, so I would say remove it from here.

I've moved v0.12 into the "Unsupported" section

evanlucas · 2017-01-23T12:06:22Z

tools/doc/html.js

+  if (lts.length)
+    html += '<b>LTS:</b> ' + lts;
+
+  const unsupported = as(['0.10.x', '5.x', '7.x']);


v7.x is still a supported version, so calling it Unsupported would be confusing IMO

v7.x is now labeled as Current

Trott · 2017-01-31T17:08:35Z

@evanlucas It looks like @chris--young has tried to address your comments. Can you PTAL when you get a chance and (if appropriate) update your review status?

Trott · 2017-01-31T17:09:37Z

This could use some more reviewers. Looping in the people who ~~gave it a +1~~ commented in the original issue: @MylesBorins @benjamingr @sam-github

Also: @nodejs/documentation

sam-github · 2017-01-31T21:04:03Z

I didn't give it a +1 in the original issue, at least I see no signs I did :-). I just CCed it to the website group.

The docs we have right now for 7.x are better to use for 4.x than than the 4.x docs were.

This is likely to misdirect people into thinking that node is like express, http://expressjs.com/en/4x/api.html, where you should always look at the docs for the version you are using.

I won't object if others find this useful, but I also won't approve.

chris--young · 2017-02-10T18:12:14Z

@sam-github any suggestions for how I can salvage this? I was thinking if I restyled the links it might be clearer that you're probably looking for the latest version (7.x) and that 0.10x - 6.x are older versions.

sam-github · 2017-02-10T18:20:53Z

@chris--young I'm +/- 0. You could try to convince me, then you'd have two approvals once you address @evanlucas 's comments :-). The PR says what it does, but doesn't say why ("I was thinking it'd be nice" doesn't count). What's the use-case?

@nodejs/documentation @nodejs/website PTAL

Trott · 2017-02-10T19:43:21Z

What's the use-case?

I would think one use case is if some API was the subject of a breaking change in 7.x but you're using 4.x or 6.x, you'll want to switch to the earlier docs easily.

sam-github · 2017-02-10T19:50:15Z

Except you won't really know that was a breaking change, unless it was the intoduction or removal of an entire API (because we don't document major changes other than that). And many of the doc improvements apply to older releases. We'd have to start being really rigorous about backporting docs. Currently, the don't backport clean to 4.x because of the .markdown to .md rename, so 4.x docs are no longer the best reference for the features in 4.x. I guess I'm saying I don't think we maintain the LTS docs rigorously enough, and we don't break the node API very much, so this isn't as useful as http://expressjs.com/en/4x/api.html vs http://expressjs.com/en/3x/api.html, and it may be dangerous to suggest we do.

On the other hand, maybe this will force us to backport all doc improvements more consistently, which would be a good thing.

toddself · 2017-02-26T17:35:42Z

I filed the original issue for this. @sam-github the idea isn't to be able to figure out what is different but to easily be able to find relevant documentation. Each major version is a major version specifically because something in an outward API changed. If i am writing code for 4.x (or even 6.x) I need to be able to quickly look up docs for that version. Right now this is hard - if you google something you always get latest. It should be trivial to get linked to the version of the docs for the API you are working with

The node 7 docs are not helpful when writing code for node 4 (or even node .12 if you are still supporting such a thing).

thefourtheye · 2017-02-26T19:59:09Z

doc/api/addons.md

@@ -1,5 +1,7 @@
 # Addons

+<!--doc_created=v0.10.0-->


doc sounds superfluous to me. How about "introduced_in"?

@thefourtheye: seems reasonable, just made that change

sam-github · 2017-02-27T16:12:29Z

Each major version is a major version specifically because something in an outward API changed.

@toddself spelling corrections in the thrown Error messages are semver-major

OK, I don't object to this, it sounds easy and like some people will find it useful, but I should point out that when the documentation is improved on master, as it often is, for features going all the way back to before LTS (including docs of APIs that existed in 4.x but were not doced), that does NOT guarantee that the docs get backported.

chris--young · 2017-03-08T02:30:15Z

@evanlucas please re-review

evanlucas · 2017-03-09T12:46:46Z

doc/api/crypto.md

@@ -1,5 +1,7 @@
 # Crypto

+<!--introduced_in=v0.10.0-->


I don't believe this is correct. (https://nodejs.org/docs/v0.3.6/api/crypto.html) crypto has been around for a while. https://nodejs.org/en/download/releases/ is a useful page to check :]

Oh cool, I had only been looking at https://nodejs.org/dist/ and must have messed up a few versions. I'll go back over all the docs and make sure these tags are the right version number.

evanlucas · 2017-03-09T12:47:12Z

doc/api/debugger.md

@@ -1,5 +1,7 @@
 # Debugger

+<!--introduced_in=v0.10.0-->


I don't think this is correct either? https://nodejs.org/dist/v0.9.12/docs/api/debugger.html

evanlucas · 2017-03-09T12:50:03Z

tools/doc/html.js

+  const a = (v) => `<a href="${href(v)}">v${v}</a>`;
+  const as = (vs) => vs.filter(lte).map(a).join(' / ');
+
+  html += 'View another version of this page <b>Current:</b> ' + a('7.x');


so one concern I have here is what will this look like when Node 8 is released? It will be released as a "Current" release line for a while before going LTS. With that, there will be a few months of layover where Node 7 is still also a "Current" release.

tinder-ydong · 2017-05-09T22:05:56Z

had same problem finding different versions of docs, and feel it'd be really convenient to add links to different versions

chris--young · 2017-08-26T18:50:59Z

@BridgeAR I don't really like the idea of merging it when we know it's broken on mobile. If you can give me till the end of the weekend i'll get it to where it needs to be.

thefourtheye · 2017-08-26T18:58:26Z

doc/api/addons.md

-Node.js Addons are dynamically-linked shared objects, written in C++, that
+<!--introduced_in=v0.10.0-->
+
+Node.js Addons are dynamically-linked shared objects, written in C or C++, that


This commit explicitly changed this to C++ abfd4bf

thefourtheye · 2017-08-26T19:01:01Z

tools/doc/html.js

@@ -31,6 +31,7 @@ const typeParser = require('./type-parser.js');
 module.exports = toHTML;

 const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
+const DOC_CREATED_REG_EXP = /<!--introduced_in=v([0-9]+).([0-9]+).([0-9]+)-->/;


The dots need to be escaped. Also, you can optionally relax the RegEx to accept optional spaces.

thefourtheye · 2017-08-26T19:13:28Z

tools/doc/html.js

+    return html;
+  }
+
+  function lte(v) {


String based comparison with v.num is not good enough. Why not split it at dots and the do integer comparison?

thefourtheye · 2017-08-26T19:14:09Z

tools/doc/html.js

+  let html = '';
+
+  if (!docCreated) {
+    console.error('Failed to add alternative version links');


Nit: If the filename is also included, it would help in debugging.

Fixes: nodejs#10726

thefourtheye · 2017-08-26T20:23:45Z

tools/doc/html.js

@@ -31,6 +31,7 @@ const typeParser = require('./type-parser.js');
 module.exports = toHTML;

 const STABILITY_TEXT_REG_EXP = /(.*:)\s*(\d)([\s\S]*)/;
+const DOC_CREATED_REG_EXP = /<!--introduced_in( )?=( )?v([0-9]+)\.([0-9]+)\.([0-9]+)-->/;


I was thinking more like

const DOC_CREATED_REG_EXP = //;

thefourtheye · 2017-08-26T22:52:00Z

tools/doc/html.js

+    { num: '5.x' },
+    { num: '4.x', lts: true },
+    { num: '0.12.x' },
+    { num: '0.10.x' },


Nit: Extra comma at the end.

Fixes: nodejs#10726

chris--young · 2017-08-28T03:30:48Z

@BridgeAR should be good to go now, unless anyone has objections

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. PR-URL: nodejs#10958 Fixes: nodejs#10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

tniessen · 2017-08-28T09:20:20Z

Landed in cacce30, thank you for the contribution! 🎉

targos · 2017-08-28T15:02:04Z

A little linting error was introduced with this commit. Fix: #15063

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. PR-URL: nodejs/node#10958 Fixes: nodejs/node#10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. PR-URL: nodejs#10958 Fixes: nodejs#10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. PR-URL: #10958 Fixes: #10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

MylesBorins · 2017-09-20T18:51:31Z

Should this be backported to v6.x-staging? If yes please follow the guide and raise a backport PR, if no let me know or add the dont-land-on label.

refack · 2017-09-20T18:56:39Z

@chris--young IMHO it would be nice to have this in 6 so as to enable cross referencing.
(Should be backported with the relevant fixes #15063, and #15420)

chris--young · 2017-09-20T20:06:02Z

@MylesBorins yea seems like a good idea. will open a pr soon

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. PR-URL: nodejs#10958 Fixes: nodejs#10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

Each page of the API documentation should have links to other versions of the same page. This will make it easier to switch between the current "live" release at nodejs.org and LTS versions. Backport-PR-URL: #15670 PR-URL: #10958 Fixes: #10726 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]>

nodejs-github-bot added the lts-watch-v6.x label Jan 23, 2017

mscdex added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels Jan 23, 2017

evanlucas suggested changes Jan 23, 2017

View reviewed changes

chris--young force-pushed the doc-version-links branch from 12b9524 to 710734b Compare January 24, 2017 02:53

nodejs-github-bot added the lts-watch-v6.x label Jan 24, 2017

chris--young force-pushed the doc-version-links branch from 710734b to 32bfaa1 Compare January 24, 2017 03:16

nodejs-github-bot added the lts-watch-v6.x label Jan 24, 2017

chris--young force-pushed the doc-version-links branch from 32bfaa1 to f1c0607 Compare January 26, 2017 20:00

nodejs-github-bot added dont-land-on-v7.x and removed lts-watch-v6.x labels Jan 26, 2017

targos removed the dont-land-on-v7.x label Jan 28, 2017

thefourtheye reviewed Feb 26, 2017

View reviewed changes

chris--young force-pushed the doc-version-links branch 2 times, most recently from 991e273 to ea244fa Compare March 8, 2017 02:28

evanlucas reviewed Mar 9, 2017

View reviewed changes

refack force-pushed the master branch from 16073c0 to fbe946b Compare April 14, 2017 04:11

chris--young force-pushed the doc-version-links branch from 48b3af1 to 7838914 Compare May 9, 2017 22:20

thefourtheye suggested changes Aug 26, 2017

View reviewed changes

doc: addressed misc review comments

d01c036

Fixes: nodejs#10726

chris--young force-pushed the doc-version-links branch from d41c2ad to d01c036 Compare August 26, 2017 19:46

thefourtheye reviewed Aug 26, 2017

View reviewed changes

thefourtheye approved these changes Aug 26, 2017

View reviewed changes

doc: use better regex

967cdba

Fixes: nodejs#10726

chris--young force-pushed the doc-version-links branch from 7047f9c to 967cdba Compare August 26, 2017 23:00

doc: made version links fit in mobile view size

6e113e2

Fixes: nodejs#10726

tniessen closed this Aug 28, 2017

MylesBorins mentioned this pull request Sep 10, 2017

v8.5.0 proposal #15308

Merged

MylesBorins added the backport-requested-v6.x label Sep 20, 2017

chris--young mentioned this pull request Sep 29, 2017

[v6.x backport] doc: add links to alternative versions of doc #15670

Closed

3 tasks

MylesBorins added backported-to-v6.x and removed backport-requested-v6.x labels Sep 29, 2017

MylesBorins mentioned this pull request Sep 29, 2017

v6.11.4 proposal #15506

Merged

doc: add links to alternative versions of doc #10958

doc: add links to alternative versions of doc #10958

Conversation

chris--young commented Jan 23, 2017 • edited Loading

Checklist

Affected core subsystem(s)

evanlucas commented Jan 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott commented Jan 31, 2017

Trott commented Jan 31, 2017 • edited Loading

sam-github commented Jan 31, 2017

chris--young commented Feb 10, 2017

sam-github commented Feb 10, 2017

Trott commented Feb 10, 2017 • edited Loading

sam-github commented Feb 10, 2017

toddself commented Feb 26, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sam-github commented Feb 27, 2017

chris--young commented Mar 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tinder-ydong commented May 9, 2017

chris--young commented Aug 26, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris--young commented Aug 28, 2017

tniessen commented Aug 28, 2017

targos commented Aug 28, 2017

MylesBorins commented Sep 20, 2017

refack commented Sep 20, 2017

chris--young commented Sep 20, 2017

chris--young commented Jan 23, 2017 •

edited

Loading

Trott commented Jan 31, 2017 •

edited

Loading

Trott commented Feb 10, 2017 •

edited

Loading