List major changes in LTS initial release

[jsumners]

From nodejs/node#41305 (comment):

Document it. Make sure it gets highlighted in the changelog for 18.x

That comment tweaked a peeve of mine. When a release line is promoted to "Current", it gets a nice post like https://medium.com/the-node-js-collection/node-js-16-available-now-7f5099a97e70 or https://nodejs.org/en/blog/release/v8.0.0/ to list all of the major changes in that release. This is great... for people following the "Current" line.

I am sure there are many people, such as myself, who only follow the LTS line. When that "Current" release toggles over to LTS, we see posts like https://nodejs.org/en/blog/release/v16.13.0/. This does not give nearly as much detail about the things LTS users should consider during their update, i.e. no detail at all. It would be very helpful if the LTS release notes included a summary of the major changes in the overall release, or at least a link to the initial summation post. (This might be a reiteration of #635 (comment).)

I'm not sure what the process is, or how it would need to change, in order to make this a reality. Making a wild guess, it could be that adding a label to things that should be called out and then referencing that label when generating the new LTS release would suffice.

[mhdawson]

@BethGriggs I wonder if some of the existing tooling could generate a list of notable changes between the new LTS and the last version of the previous LTS line, or is that currently done manually?

[BethGriggs]

@mhdawson, we can use branch-diff to generate a list of all notable changes (and/or majors) between the two LTS lines with our tooling. But, branch-diff would output in commit/PR list form, which is not particularly consumable.

An option would be to write a script to collate the more consumable 'Notable Change' sections (example) from the release blog posts between the previous LTS and new LTS. That would take a lot of tweaking to order, remove duplicates, etc. Also, if we're including notable changes from Node.js 15 in the Node.js 16 LTS post, we'd need to confirm that all of those notable changes also apply Node.js 16 - which may not always be the case if something has been reverted/undergone subsequent changes.

Agreed though, at a minimum, we should point users to where they can find useful information such as in the release post for the major version (v16.0.0), release announcements, and prior notable changelog entries. To achieve this we'd just need to PR the instruction into our LTS release preparation guide.

[mhdawson]

@BethGriggs thanks for the options. Sounds like your last suggestion would be a great first step.

[jsumners]

Agreed.

[jsumners]

Should I be doing something around this?

[mhdawson]

@BethGriggs in response to the question from @jsumners would it be helpful if he worked on writing the script for your suggestion:

An option would be to write a script to collate the more consumable 'Notable Change' sections (example) from the release blog posts between the previous LTS and new LTS. That would take a lot of tweaking to order, remove duplicates, etc. Also, if we're including notable changes from Node.js 15 in the Node.js 16 LTS post, we'd need to confirm that all of those notable changes also apply Node.js 16 - which may not always be the case if something has been reverted/undergone subsequent changes.

[BethGriggs]

would it be helpful if he worked on writing the script for your suggestion:

IMO not really - as it's possible today just by running a series of branch-diff commands. The challenge is the burden put on the releaser to trawl through likely 100s of commits and verify they apply, remove reverts and duplicates, and word them in a consumable form.

The key initial action is the following:

Agreed though, at a minimum, we should point users to where they can find useful information such as in the release post for the major version (v16.0.0), release announcements, and prior notable changelog entries. To achieve this we'd just need to PR the instruction into our [LTS release preparation guide]

(edit: added more context to quote)

[targos]

The challenge is the burden put on the releaser to trawl through likely 100s of commits and verify they apply, remove reverts and duplicates, and word them in a consumable form.

TBH I will probably never prepare any LTS transition release if that burden is put on the releaser.

[mhdawson]

@BethGriggs thanks for the clarification. Should this issue stay open until we update some doc with respect to

Agreed though, at a minimum, we should point users to where they can find useful information such as in the release post for the major version (v16.0.0), release announcements, and prior notable changelog entries. To achieve this we'd just need to PR the instruction into our [LTS release preparation guide]

?

[AugustinMauroy]

cc @nodejs/userland-migrations that can help us to know what we have to cover

[RafaelGSS]

For folks that want a list of semver-major commits between one line and another, run:

$ branch-diff upstream/vN-1.x upstream/vN.x --require-label=semver-major --group --filter-release --markdown

Where N is the LTS line.

[jsumners]

@RafaelGSS are you suggesting that as a solution for folks that read the major release news posts?

[AugustinMauroy]

also list of commit that is semver is kind on undigest for a lot of user

[RafaelGSS]

@RafaelGSS are you suggesting that as a solution for folks that read the major release news posts?

No, I'm suggesting this usage for whatever solution we design for this - either in the LTS blog post or userland-migration initiative.