Repository navigation
List major changes in LTS initial release #716
Description
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.
Activity
mhdawson commentedon Jan 4, 2022
@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 commentedon Jan 4, 2022
@mhdawson, we can use
branch-diffto generate a list of all notable changes (and/or majors) between the two LTS lines with our tooling. But,branch-diffwould 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 commentedon Jan 7, 2022
@BethGriggs thanks for the options. Sounds like your last suggestion would be a great first step.
jsumners commentedon Jan 7, 2022
Agreed.
jsumners commentedon Feb 11, 2022
Should I be doing something around this?
mhdawson commentedon Feb 14, 2022
@BethGriggs in response to the question from @jsumners would it be helpful if he worked on writing the script for your suggestion:
BethGriggs commentedon Feb 17, 2022
IMO not really - as it's possible today just by running a series of
branch-diffcommands. 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:
(edit: added more context to quote)
targos commentedon Feb 17, 2022
TBH I will probably never prepare any LTS transition release if that burden is put on the releaser.
mhdawson commentedon Feb 18, 2022
@BethGriggs thanks for the clarification. Should this issue stay open until we update some doc with respect to
?
AugustinMauroy commentedon Oct 18, 2025
cc @nodejs/userland-migrations that can help us to know what we have to cover
RafaelGSS commentedon Oct 19, 2025
For folks that want a list of semver-major commits between one line and another, run:
Where N is the LTS line.
jsumners commentedon Oct 19, 2025
@RafaelGSS are you suggesting that as a solution for folks that read the major release news posts?
AugustinMauroy commentedon Oct 19, 2025
also list of commit that is semver is kind on undigest for a lot of user
RafaelGSS commentedon Oct 19, 2025
No, I'm suggesting this usage for whatever solution we design for this - either in the LTS blog post or userland-migration initiative.
jsumners commentedon Oct 19, 2025
I thought so, but wanted to make sure.
richardlau commentedon Oct 27, 2025
For Node.js 24 I've made an attempt at writing one for going from Node.js 22 LTS to 24 LTS: nodejs/nodejs.org#8270
FTR what is there took a few days to put together and has not been an enjoyable process.
results in 190 commits and filtering that down and making it readable is a lot of work that I don't think we can realistic put the responsibility onto @nodejs/releasers.
I think most people will look at the OP/title of this issue and agree that it is a good idea, but the challenge is how to make it happen. If anyone has ideas, well the data is all public so feel free to provide a demonstration of how it can be done in a sustainable fashion.
Possibly the one suggestion that could work is in nodejs/node#18836 -- get the wider collaborator base to contribute on
mainand cut the document along with the code when branching (but would the documentation would still need to be maintained in the staging branch for the even numbered release). The problem with that is then it is not so easy to issue any updates to the doc as that implies cutting a new Node.js version (minor/patch).richardlau commentedon Oct 27, 2025
FWIW the content may end up in nodejs/nodejs.org#8053 instead, which would introduce an entire migration section to the website.
jsumners commentedon Oct 28, 2025
I don't know how things are handled when composing the announcements. I would imagine it's easier if major notable features are collected or tagged along the way. Imagine if
new Buffer()were hard deprecated in 9.whatever and then, when 10.0.0 was released, the 10.0.0 release notes never mentioned it and only mentioned whatever changed between the last 9 minor release and the new major. Folks that are only paying attention to the LTS major releases, i.e. currently every even release, would have missed this very important notice.I really don't want to make things more difficult for releasers. But I can tell you that I have no clue what is really important in the last few LTS majors because I stopped paying any attention to the odd releases.