content(userland-migration): make up to date

[AugustinMauroy]

Description

Reflect current status of the userland-migration initiative.
Add migrations section with article
move userland migration subesection to article

Related Issues

No related issues

Check List

• I have read the Contributing Guidelines and made commit messages that follow the guideline.
• I have run pnpm format to ensure the code follows the style guide.
• I have run pnpm test to check if all tests are passing.
• I have run pnpm build to check if the website builds without errors.
• NA I've covered new added functionality with unit tests if necessary.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
nodejs-org	Ready	Preview	Oct 29, 2025 1:02pm

[Copilot]

Pull Request Overview

Updates the userland-migration documentation to reflect current status and showcase new codemods for Node.js version migrations and ecosystem transitions.

• Reorganizes navigation structure from "migrations" to "userland-migrations" for consistency
• Adds comprehensive documentation for v20-to-v22 and v14-to-v16 migration codemods
• Introduces ecosystem migration documentation for transitioning from external tools to native Node.js features

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/i18n/src/locales/en.json	Updates navigation labels and adds new migration page entries
apps/site/pages/en/learn/userland-migrations/v20-to-v22.md	Documents import assertions to attributes codemod for Node.js v22 migration
apps/site/pages/en/learn/userland-migrations/v14-to-v16.md	Documents createRequire and rmdir codemods for Node.js v16 migration
apps/site/pages/en/learn/userland-migrations/introduction.md	Enhanced introduction with comprehensive usage guide and best practices
apps/site/pages/en/learn/userland-migrations/ecosystem.md	Documents TypeScript specifier correction codemod for ecosystem migration
apps/site/pages/en/learn/migrations/introduction.md	Removes old migration documentation file
apps/site/navigation.json	Updates navigation structure to use new userland-migrations path and adds new pages

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.61%. Comparing base (a49f65c) to head (47f8b45).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8053      +/-   ##
==========================================
- Coverage   76.62%   76.61%   -0.02%     
==========================================
  Files         117      117              
  Lines        9751     9746       -5     
  Branches      328      328              
==========================================
- Hits         7472     7467       -5     
  Misses       2277     2277              
  Partials        2        2              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[avivkeller]

Did a cursory review. There's definitely a lot of work to be done before this can land, so I'm blocking for now.

[AugustinMauroy]

Did a cursory review. There's definitely a lot of work to be done before this can land, so I'm blocking for now.

Olay i had opened the pr to have review on structure/aproeach

[AugustinMauroy]

@avivkeller I have a compromise to propose. We will proceed with this file structure even if you are not satisfied with it. We will then reopen issue #7267 and find a long-term solution for where to store these documents.

[avivkeller]

I'm still strongly -1 on articles for specific Codemods. Those should be blog posts, if anything.

cc @nodejs/nodejs-website @nodejs/marketing for opinions

[JakobJingleheimer]

I'm still strongly -1 on articles for specific Codemods. Those should be blog posts, if anything.

cc @nodejs/nodejs-website @nodejs/marketing for opinions

If I'm understanding right, the current article(s) are listing specific codemods as part of a major node migration, which means that list will be frozen once complete. That seems okay to me, but perhaps redundant: I would instead just list/link to the major migration recipe, which will itself list the individual migrations anyway.

P.S. I think we definitely should not statically list all migrations available. That would be an untenable maintenance burden, and we already have tools (github, the codemod registry, and perhaps others) that do it well already.

[AugustinMauroy]

@avivkeller other solution using doc-kit with web generator on userland-migration repo so:

1. we will have search + super UI
2. document will lived in same repo than source so easy to maintain
3. we can point migration.nodejs.org on nodejs.github.io/userland-migrations

[ovflowd]

I'm neutral here, but agree that codemods are something more "temporal", so I agree with the notion of this being better suited for a blog post?

[AugustinMauroy]

I'm neutral here, but agree that codemods are something more "temporal", so I agree with the notion of this being better suited for a blog post?

In theory, yes. But in our case, it doesn't work because a blog post is read once by the user when it is published (from a post on the RSS feed network). But here, we haven't yet completed all the migrations to cover a complete version, so once they've read it, they won't come back to the post even if new codemod is added to it.

And frankly, we need visibility to help with adoption so that we can then get feedback.

[AugustinMauroy]

Hello @nodejs/tsc, I would like to hear your opinion on the situation.

This PR updates the resource on userland-migrations to include everything that has been produced by the initiative and introduces a new page.
For historical context, the userland-migrations initiative was launched by Jacob after the Dublin Collab Summit in 2024. It aims to provide codemods to handle deprecations, breaking changes, or feature adoption. That is why the issue #7267 was created to determine where we should put these resources. It was decided that the learn section would be the right place.

And @avivkeller blocks the idea with the following argument I am linking to the message so as not to paraphrase it

• content(userland-migration): make up to date #8053 (comment)
• content(userland-migration): make up to date #8053 (comment)

So the question that arises is, "Where should we put the migration guides?"

Option 1: Learn section
Simply what this pr offers

Option 2: blog category
Have a dedicated category and keep the same md files.
But the downside is that the posts will have to change when we cover more deprecation. And the concept of a blog post is more about having a document that is posted online and does not change, like a newspaper article. My understanding of the life cycle of a post is that it is posted and shared on social media, then readers read it, and it is rare that we reread a post.

Option 3: dedicated section
I think this is ideal. It would be to have a new section next to About and Learn that covers all migrations. And that solves all the problems (IMO).
But the problem with this approach is that it will fill up the navigation bar, which is already quite full.

Option 4: dedicated website
The idea would be to have migrations.nodejs.org and the sources would be on the userland-migration repo. The host would be done with GH pages and the DANS would point to nodejs.github.io/userland-migration. And to build it, we would use doc-kit, the tool that the website team created for the redesign of the API doc.
The problem here is that it adds a new domain name and is completely separate, which is the opposite of the initial idea of highlighting the initiative. What's more, it adds extra maintenance.
For me, this is the worst approach.

[avivkeller]

@AugustinMauroy in the future, before escalating to the technical steering committee, we can always have a web team meeting.

However, I maintain my stance that these should not be articles. An article for every code mod released is not a viable solution. Rather, I think, a single article linking to the code mod repository, where those lists can be maintained is better.

A code mod here and there could also be a blog post, again, without the need of individual learn articles for specific code mods.

[avivkeller]

A fifth option, that is, have a single learn articles explaining the code mods, and linking to the dedicated repository, would best, imo.

[AugustinMauroy]

@AugustinMauroy in the future, before escalating to the technical steering committee, we can always have a web team meeting.

FYI: I first asked Ruy (because he speaks French, to avoid the language barrier) if it was worth pinging the TSC. And I also didn't add it to the TSC agenda for a formal vote, just to ask for their opinion/feelings.

Furthermore, if I am not mistaken, at the moment the website team is not responsible for the content, so it makes sense to me not to put it in our agenda.

without the need of individual learn articles for specific code mods.

I don't get what you mean on this point. I don't think I wrote an article per codemod. I wrote migration guides per version and one for the ecosystem.

was based on where the content should be located, not on the content itself.
Since this review, a website team meeting has taken place, as well as a userland migrations meeting, so this issue has been resolved.

[richardlau]

Approval for apps/site/pages/en/blog/migrations/v22-to-v24.mdx only (I defer reviewing the rest of this PR to the website team).

[AugustinMauroy]

cc @nodejs/userland-migrations @nodejs/nodejs-website

[JakobJingleheimer]

It looks like the only changes since I last approved are some dates in metadata?

[AugustinMauroy]

It looks like the only changes since I last approved are some dates in metadata?

more thing as been added on v22-to-v24 about platform support, compilation support ...

[bmuenzenmeyer]

so sorry @AugustinMauroy and @JakobJingleheimer for the last second review - I know that's a particular pet peeve and I hate to know I am perpetuating it for you. Hope this is simple stuff

[AugustinMauroy]

@bmuenzenmeyer thansk for the grammar fix

[melroy89]

I love these migrations a lot!

Question that doesn't seems to be documented yet: How can I run all the migrations with the nodejs scope?

Eg. Basically I want to run all the relevant node.js migrations to bring my whole project up to date with a single command.

If this is possible. Maybe explain the command as well under the "How to use.." heading?..

[AugustinMauroy]

I love these migrations a lot!

Question that doesn't seems to be documented yet: How can I run all the migrations with the nodejs scope?

Eg. Basically I want to run all the relevant node.js migrations to bring my whole project up to date with a single command.

If this is possible. Maybe explain the command as well under the "How to use.." heading?..

It's planned to have a codemod like @nodejs/v22-to-v24 but for that we need to cover all deprecation (we are on it)