doc,tools: get altDocs versions from CHANGELOG.md

[richardlau]

Parse CHANGELOG.md for versions of Node.js used by the documentation
feature View another version so that we don't have to manually update
the list when we cut a new version or transition a release to LTS.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• commit message follows commit guidelines

[BridgeAR]

The code itself LGTM while I would prefer not to use a fixture. That could be done by
a) not reading the whole changelog entry but only a small top part of the file
b) by checking that the current output is the "minimum" expectation instead of the absolute truth and that there could be more versions and more lts entries.

That way it would be easier to detect changes that might break this (e.g. parts of the file structure would be changed or old entries would be moved). That is not as likely but it still seems a possibility.

But I'm also fine with the code as is. This is definitely an improvement over the current situation!

[richardlau]

I've just realised this isn't going to work as expected outside of master because we don't port the CHANGELOG.md changes backwards (e.g. https://github.com/nodejs/node/blob/v8.x/CHANGELOG.md doesn't know of any version greater than 8). We do port the altDocs changes, e.g. for Node.js 8:

node/tools/doc/html.js

Lines 170 to 181 in 07458ba

	const versions = [
	{ num: '11.x' },
	{ num: '10.x', lts: true },
	{ num: '9.x' },
	{ num: '8.x', lts: true },
	{ num: '7.x' },
	{ num: '6.x', lts: true },
	{ num: '5.x' },
	{ num: '4.x', lts: true },
	{ num: '0.12.x' },
	{ num: '0.10.x' }
	];

which allows docs for, e.g. Node.js 8, to point to newer versions, e.g. Node.js 10.

[richardlau]

I've just realised this isn't going to work as expected outside of master because we don't port the CHANGELOG.md changes backwards (e.g. https://github.com/nodejs/node/blob/v8.x/CHANGELOG.md doesn't know of any version greater than 8). We do port the altDocs changes, e.g. for Node.js 8:

node/tools/doc/html.js

Lines 170 to 181 in 07458ba

	const versions = [
	{ num: '11.x' },
	{ num: '10.x', lts: true },
	{ num: '9.x' },
	{ num: '8.x', lts: true },
	{ num: '7.x' },
	{ num: '6.x', lts: true },
	{ num: '5.x' },
	{ num: '4.x', lts: true },
	{ num: '0.12.x' },
	{ num: '0.10.x' }
	];

which allows docs for, e.g. Node.js 8, to point to newer versions, e.g. Node.js 10.

And I've just realised that the table for Node.js 8 doesn't match the table in master:

node/tools/doc/html.js

Lines 396 to 407 in b230833

	const versions = [
	{ num: '11.x' },
	{ num: '10.x', lts: true },
	{ num: '9.x' },
	{ num: '8.x', lts: true },
	{ num: '7.x' },
	{ num: '6.x', lts: true },
	{ num: '5.x' },
	{ num: '4.x' },
	{ num: '0.12.x' },
	{ num: '0.10.x' },
	];

because we haven't backported #20904 (which removed the LTS label from Node.js 4).

[BridgeAR]

@richardlau we could check the file in the repository instead. That's not a great solution but it would at least always work in case there's a network connection. That way it's always up to date.

[richardlau]

@richardlau we could check the file in the repository instead. That's not a great solution but it would at least always work in case there's a network connection. That way it's always up to date.

Yeah, less than ideal but probably okay? I'll do that later (after I've eaten).

I've pushed a change to remove the test fixture and do sanity checks on the versions (e.g. LTS releases are never odd numbered releases) rather than a deepStrictEqual assertion.

[richardlau]

@BridgeAR Quick thought -- If we're going to need a network connection we might be better off reading schedule.json from the Release repository (with some checks that the version start date isn't in the future to avoid picking up unreleased versions, e.g. v13) rather than relying on the changelog?

[BridgeAR]

@richardlau I thought about that as well and it is indeed the perfect data. The reason why I still prefer the changelog approach right now is that it's another repository and we update that file manually. We did lack behind before (just a bit but still) and might forget to update that file at times while that would not happen with the changelogs.

[richardlau]

@richardlau I thought about that as well and it is indeed the perfect data. The reason why I still prefer the changelog approach right now is that it's another repository and we update that file manually. We did lack behind before (just a bit but still) and might forget to update that file at times while that would not happen with the changelogs.

We did forget to update the list of versions in the changelog, see #27414 (this step is in the release process docs being proposed in #25497). I've kept with parsing the changelog for now (albeit the code now fetches the version from the master branch) since I'd already written the parsing regular expressions.

Since the code now fetches from the master branch building the docs and the newly added test will make an Internet request.

cc @nodejs/documentation

[BridgeAR]

@richardlau we could also just parse the filenames instead of reading the entries from the main changelog.md. I doubt that we'll ever forget a to add such entry. But I'm actually happy with either implementation as long as it automates the process.

The test itself should probably be moved to test/internet.

[richardlau]

@richardlau we could also just parse the filenames instead of reading the entries from the main changelog.md. I doubt that we'll ever forget a to add such entry. But I'm actually happy with either implementation as long as it automates the process.

The test itself should probably be moved to test/internet.

@BridgeAR We won't be able to determine LTS status by just parsing filenames.

I've moved the test to test/internet and also added a test for the previous semver major (i.e. if master is v13.0.0-pre it checks for 12.x). This additional test should catch the cases where we forget to update the main changelog (i.e. when 13.x is released and master moves to v14.0.0-pre the test will fail if Node.js 13 is not added to the main changelog).

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/23097/

[ChALkeR]

#27658 (comment) is also relevant here -- the LTS labels in current master don't seem correct.

4.x and 6.x are both EOL (and both were LTS previously), so they should have identical labelling (either both have LTS label or both not have it, or both have an EOL label).

Refs: #20904 nodejs/Release#440

[richardlau]

#27658 (comment) is also relevant here -- the LTS labels in current master don't seem correct.

4.x and 6.x are both EOL (and both were LTS previously), so they should have identical labelling (either both have LTS label or both not have it, or both have an EOL label).

Refs: #20904 nodejs/Release#440

I pushed an update to #27658 that makes the LTS status consistent (both 4 and 6 no longer have it). Once the changelog is consistent this PR will make the LTS labels in the "View another version" drop down in the built docs consistent automatically (provided we keep the changelog accurate).

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/23145/

[addaleax]

@richardlau This is ready, right? Do you want to go ahead and land this?

[richardlau]

@richardlau This is ready, right? Do you want to go ahead and land this?

I think it was. It’s a long weekend here in UK (public holiday on Monday) so it’ll be Tuesday at the earliest before I can land this.

[richardlau]

@richardlau This is ready, right? Do you want to go ahead and land this?

I think it was. It’s a long weekend here in UK (public holiday on Monday) so it’ll be Tuesday at the earliest before I can land this.

node-core-utils says this isn't ready to land because changes were pushed after the review. Taken the opportunity to rebase and squash the fixup commits and address @Trott 's suggested changes to avoid the use of sanity (as in sanity checks) in the comments.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/23452/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/23453/

[Trott]

Still LGTM.

[richardlau]

Still LGTM.

I'd assumed (perhaps naively) that this LGTM should have satisfied node-core-utils, but it does not:

-bash-4.2$ git-node land 27661
✔  Done loading data for nodejs/node/pull/27661
----------------------------------- PR info ------------------------------------
Title      doc,tools: get altDocs versions from CHANGELOG.md (#27661)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     richardlau:autoaltdocs -> nodejs:master
Labels     doc, review wanted, tools
Commits    1
 - doc,tools: get altDocs versions from CHANGELOG.md
Committers 1
 - Richard Lau <riclau@uk.ibm.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/27661
Reviewed-By: Rich Trott <rtrott@gmail.com>
--------------------------------------------------------------------------------
   ⚠  Commits were pushed since the last review:
   ⚠  - doc,tools: get altDocs versions from CHANGELOG.md
   ℹ  Last Full PR CI on 2019-05-29T12:26:38Z: https://ci.nodejs.org/job/node-test-pull-request/23453/
   ℹ  This PR was created on Sun, 12 May 2019 17:14:09 GMT
   ✔  Approvals: 1
   ✔  - Rich Trott (@Trott) (TSC): https://github.com/nodejs/node/pull/27661#pullrequestreview-236953915
--------------------------------------------------------------------------------
? This PR is not ready to land, do you want to continue?

There's a couple of reasons for this:

1. The comment in question doesn't get recognized by the regular expression https://github.com/nodejs/node-core-utils/blob/1e9daeb15475efdfea4a418686395299ad892149/lib/reviews.js#L7. I'd be a little wary relaxing the regexp as, for example, I'm not sure we'd want to treat the LGTM in doc,tools: get altDocs versions from CHANGELOG.md #27661 (review) as an approval.
2. As far as I can tell the code that checks commits since the last review only looks at reviews and not LGTM's (assuming they were detected) in the comments.

[Trott]

Landed in 4ec6135