History section of ECMAScript modules documentation is confusing

[jmm]

Affected URL(s)

https://nodejs.org/docs/latest-v14.x/api/esm.html https://nodejs.org/docs/latest-v16.x/api/esm.html

Description of the problem

Hello, the top-level history section of this documentation in the following versions include the following entries:

12.x LTS documentation (v12.22.11):

v12.22.0	Stabilize modules implementation.
v12.20.0	Remove experimental modules warning.

14.x LTS documentation (v14.19.1):

v14.17.0	Stabilize modules implementation.
v14.0.0, v13.14.0	Remove experimental modules warning.

16.x LTS documentation (v16.14.2):

v15.3.0, v12.22.0	Stabilize modules implementation.
v14.0.0, v13.14.0, v12.20.0	Remove experimental modules warning.

When reading the v14 documentation it makes it sound like stabilizing the implementation first happened in v14.17.0 (and not in any 12.x version).

When reading the v16 documentation it makes it sound like stabilizing the implementation first happened in v12.22.0, and either would have been in v14.0.0 or not in any 14.x version.

I'd expect the history in each version to include the entries for lower versions. So in this case I'd expect the 14.x history to include the 12.x entries, and the 16.x history to include the 14.x and 12.x entries. But 14.x omits some of the 12.x stuff and 16.x omits some of the 14.x stuff (but includes the 12.x stuff).

The implementation was stabilized in v12.22.0, v14.17.0, and v16.0.0, right?

Also, how would you clearly be able to tell when something like "Stabilize modules implementation" was the case in an X.0.0 version? Like in the 16.x documentation, should it say ">= v15.3.0"?

[aduh95]

That's an unfortunate consequence of how backporting works in Node.js. Only the information for the current release line is accurate, when a feature gets backported to a release line, the documentation change is almost never "forward-ported" to the other release lines – but the correct information is commited to the master branch, which you can expect to be always correct.

The implementation was stabilized in v12.22.0, v14.17.0, and v16.0.0, right?

It was stabilized in v12.22.0, v14.17.0, and v15.3.0. If you check the HTML render for v17.x, you can see that the information is up-to-date there: https://nodejs.org/api/esm.html
Node.js does a yearly semver-cutoff, which takes the up-to-date information for all release line from the master branch, which is why v17.x docs show the correct info in this case.

[aduh95]

Also, how would you clearly be able to tell when something like "Stabilize modules implementation" was the case in an X.0.0 version? Like in the 16.x documentation, should it say ">= v15.3.0"?

The documentation assume the reader is familiar with Node.js release process. I'm not convinced that is a fair assumption, but I also don't have a better system to suggest.

There are two types of release lines for Node.js:

• Current
• LTS

All vx.0.0 releases are always Current. If x is even, the release line will switch to LTS 6 months later.

To land on a LTS release line, the feature must first land on a Current release line for at least two weeks.

With all of that in mind, you can take out that:

• The stabilization first landed on v15.3.0 (Current)
• It was then backported to v14.17.0 (LTS) and v.12.22.0 (LTS)

So the actual range would be ^12.22.0 || ^14.17.0 || >=15.3.0.

When reading the v16 documentation it makes it sound like stabilizing the implementation first happened in v12.22.0, and either would have been in v14.0.0 or not in any 14.x version.

Since it says it landed on v15.3.0, you can actually know that it wasn't on v14.0.0. I can see how you could conclude that it was never backported to v14.x, even though it was. If you want up-to-date info for the v14.x release line, you should check v14.x docs.

[iamgabrielsoft]

I think there is a good reason node uses this format when releasing update for upcoming version. To provide stability

[jmm]

@aduh95 Thanks for your insight!

If that's the upshot, it seems to considerably limit the usefulness of having a history. It's especially confusing that the v16 history includes the v12 parts and some of the v14 parts, but not other v14 parts.

Setting aside the mechanics involved for the moment, do you agree that it would be better for the higher version history to consistently include the lower version history? So for example in this case, the 16.x history to include v14.17.0 for "Stabilize modules implementation."

[aduh95]

I don't disagree, if you open a PR to fix that on v16.x-staging, it might get accepted.

[jmm]

Ok, thank you. I appreciate you taking the time to make thoughtful responses and explain the context 🙌

I'm not personally going to be able to fix it in the foreseeable future, but hopefully someone will take an interest in it.

And rather than doing it on a case by case basis, maybe there's an easier way to manage it that can be worked out. I don't know anything about the current process beyond what you described, but if it's not already setup this way, maybe there's some central location (master branch?) that can store that data for all versions in a machine readable way that the documentation generation process can read from and include the entries for lower versions.

[aduh95]

//cc @nodejs/lts

[targos]

LTS releases are relatively independent from each other. Even if we ported version metadata between releases, it would only be reflected on the website after a new release of the other lines is published.
I agree there is something to fix here, but it would be better to take this problem into account when working on a bigger refactor of how the documentation is managed by the project.

[jmm]

Thank you @targos (and again, @aduh95). I don't know if you have thoughts on how to go about or track that -- for the time being I'll leave this ticket open so there's something on the radar.