content(userland-migration): make up to date

[AugustinMauroy]

Description

Reflect current status of the userland-migration initiative. Plus show new codemods.

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 10, 2025 9:38pm

[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.69%. Comparing base (0b90e2c) to head (ddc4cdb).
⚠️ Report is 25 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8053      +/-   ##
==========================================
+ Coverage   76.56%   76.69%   +0.13%     
==========================================
  Files         115      115              
  Lines        9602     9643      +41     
  Branches      323      322       -1     
==========================================
+ Hits         7352     7396      +44     
+ Misses       2249     2246       -3     
  Partials        1        1              

☔ 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.

[AugustinMauroy]

Okay friend, I redid everything afterwards:

• the discussion between Claudio and Alex
• the sync meeting between Jacob and Alex
• and the userland migrations meeting

[avivkeller]

Okay, during today's meeting, we discussed moving forward with, as it relates to this PR,

• Putting Migration guides in the Blog.
• Putting concepts related to migrations in Learn.

[avivkeller]

Does this really have to be an alert box?

[AugustinMauroy]

I think it's cool and it's clearly show to the user a warning.

[avivkeller]

That doesn't need to be a warning? It's not urgent, it can easier be part of the article

[AugustinMauroy]

IMO it's should warn the user so use alert box. also using blackquote will be wrong on this case because the color of it is green is associated to ok/good thing.

Maybe info alertBox ?

[avivkeller]

Started review, same tropes throughout the articles.

Thank you!

[avivkeller]

Let's link the package in the title

[AugustinMauroy]

like this ?

## [`util-print-to-console-log`](https://app.codemod.com/registry/@nodejs/util-print-to-console-log)

[avivkeller]

Yes

[AugustinMauroy]

I was thinking about that but our heading is already link ...

[avivkeller]

Let's wait for v24 to officially get it's LTS badge

[AugustinMauroy]

good idea !

[AugustinMauroy]

I think we can remove the block label since both website and userland migration agree on the aproach !