content(userland-migration): make up to date
#8053
Conversation
AugustinMauroy
added
content
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
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 Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #8053 +/- ##
==========================================
+ Coverage 76.43% 76.49% +0.05%
==========================================
Files 115 115
Lines 9643 9663 +20
Branches 316 316
==========================================
+ Hits 7371 7392 +21
+ Misses 2271 2270 -1
Partials 1 1 ☔ View full report in Codecov by Sentry. |
Olay i had opened the pr to have review on structure/aproeach |
|
@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. |
|
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. |
|
@avivkeller other solution using doc-kit with web generator on
|
|
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
force-pushed
the
content(`userland-migration`)
branch
from
5a6d2f6 to
e98d32d
Compare
|
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. And @avivkeller blocks the idea with the following argument I am linking to the message so as not to paraphrase it
So the question that arises is, "Where should we put the migration guides?" Option 1: Learn section Option 2: blog category Option 3: dedicated section Option 4: dedicated website |
|
@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. |
|
A fifth option, that is, have a single learn articles explaining the code mods, and linking to the dedicated repository, would best, imo. |
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.
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
force-pushed
the
content(`userland-migration`)
branch
from
5159749 to
a009faf
Compare
|
Okay friend, I redid everything afterwards:
|
|
Okay, during today's meeting, we discussed moving forward with, as it relates to this PR,
|
| <AlertBox level="warning" title="!"> | ||
| This article cover a part of the migration from Node.js v12 to v14. The | ||
| userland migrations team is working on more codemods to help you with the | ||
| migration. | ||
| </AlertBox> |
There was a problem hiding this comment.
Does this really have to be an alert box?
There was a problem hiding this comment.
I think it's cool and it's clearly show to the user a warning.
There was a problem hiding this comment.
That doesn't need to be a warning? It's not urgent, it can easier be part of the article
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
Why do we need an alert at all? Nothing here is urgent
There was a problem hiding this comment.
I mean it's not urgent it's a warning.
We can remove them but it's good thing to have IMP
There was a problem hiding this comment.
Without the warning, people might think that it's fine to launch production with just that, even though parts are missing.
There was a problem hiding this comment.
I think the warning is a bit much 😅 Is there an info box instead of a warning?
| @@ -0,0 +1,55 @@ | |||
| --- | |||
There was a problem hiding this comment.
Let's wait for v24 to officially get it's LTS badge
|
I think we can remove the block label since both website and userland migration agree on the aproach ! |
|
cc @avivkeller does the PR look good for you? |
|
|
||
| In Node.js 24, the `fs` module introduced a runtime deprecation for `F_OK`, `R_OK`, `W_OK`, and `X_OK` getters exposed directly on `node:fs`. Get them from `fs.constants` or `fs.promises.constants` instead. | ||
|
|
||
| So this codemod handle [DEP0176](https://nodejs.org/api/deprecations.html#DEP0176). |
There was a problem hiding this comment.
And others like it
| So this codemod handle [DEP0176](https://nodejs.org/api/deprecations.html#DEP0176). | |
| This codemod handles [DEP0176](https://nodejs.org/api/deprecations.html#DEP0176). |
|
|
||
| # Userland Migrations | ||
|
|
||
| Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle breaking changes. These are built in collaboration with [Codemod](https://codemod.com), a platform focused on making it easy to build, share, and run codemods. |
There was a problem hiding this comment.
| Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle breaking changes. These are built in collaboration with [Codemod](https://codemod.com), a platform focused on making it easy to build, share, and run codemods. | |
| Node.js offers migrations for "userland" code (anything outside the node executable) to help adopt new features and handle deprecations and breaking changes. These are built in collaboration with [Codemod](https://codemod.com), a platform for easily building, sharing, and running codemods. |
| <AlertBox level="warning" title="!"> | ||
| This article cover a part of the migration from Node.js v12 to v14. The | ||
| userland migrations team is working on more codemods to help you with the | ||
| migration. | ||
| </AlertBox> |
There was a problem hiding this comment.
I think the warning is a bit much 😅 Is there an info box instead of a warning?
| - [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026): `util.print` ➜ `console.log` | ||
| - [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027): `util.puts` ➜ `console.log` | ||
| - [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028): `util.debug` ➜ `console.error` | ||
| - [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029): `util.error` ➜ `console.error` |
There was a problem hiding this comment.
nit: I think this is using an emoji instead of the the glyph.
| - [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026): `util.print` ➜ `console.log` | |
| - [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027): `util.puts` ➜ `console.log` | |
| - [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028): `util.debug` ➜ `console.error` | |
| - [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029): `util.error` ➜ `console.error` | |
| - [DEP0026](https://nodejs.org/api/deprecations.html#DEP0026): `util.print` → `console.log` | |
| - [DEP0027](https://nodejs.org/api/deprecations.html#DEP0027): `util.puts` → `console.log` | |
| - [DEP0028](https://nodejs.org/api/deprecations.html#DEP0028): `util.debug` → `console.error` | |
| - [DEP0029](https://nodejs.org/api/deprecations.html#DEP0029): `util.error` → `console.error` |
|
|
||
| ## `import-assertions-to-attributes` | ||
|
|
||
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. |
There was a problem hiding this comment.
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. | |
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/), but during the during the transition to stage 4, the `assert` keyword was replaced with an `with` attribute on the `import` statement. |
|
|
||
| During the process of TC39 standardization, the `import assert` feature was introduced to allow importing [JSON modules](https://tc39.es/proposal-json-modules/) but during the during the transition to stage 4, the `assert` keyword was removed and replaced with an `with` attribute on the `import` statement. | ||
|
|
||
| So in [node.js v22](https://nodejs.org/fr/blog/release/v22.0.0#other-notable-changes), the `import assert` feature was removed and you need to use the `with` attribute instead. |
There was a problem hiding this comment.
| So in [node.js v22](https://nodejs.org/fr/blog/release/v22.0.0#other-notable-changes), the `import assert` feature was removed and you need to use the `with` attribute instead. | |
| So in [node.js v22](https://nodejs.org/fr/blog/release/v22.0.0#other-notable-changes), the `import assert` feature was removed and the `with` attribute is required instead. |
| The [Codemod registry](https://codemod.link/nodejs-official) provides a list of available codemods for Node.js. | ||
| Some codemods may not be included in the following resources but are still available because they are not related to a specific migration to a Node.js version. Since we only list codemods for EoL deprecations, you may need to explore the registry for other codemods that could be useful for your migrations. |
There was a problem hiding this comment.
Is the line-break intentional? (should these be two separate paragraphs, or just 1)
| The [Codemod registry](https://codemod.link/nodejs-official) provides a list of available codemods for Node.js. | ||
| Some codemods may not be included in the following resources but are still available because they are not related to a specific migration to a Node.js version. Since we only list codemods for EoL deprecations, you may need to explore the registry for other codemods that could be useful for your migrations. | ||
|
|
||
| > Please note that if you are logged into the Codemod platform, you can like these posts. This shows us that our work is valuable. |
There was a problem hiding this comment.
| > Please note that if you are logged into the Codemod platform, you can like these posts. This shows us that our work is valuable. | |
| > Please note that if you are logged into the Codemod platform, you can like these posts. This helps us to see what users find valuable. |
| ## Feedback | ||
|
|
||
| If you have any feedback or suggestions for improvements, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). |
There was a problem hiding this comment.
Let's direct them to discussions instead and keep issues for bugs and similar.
| If you have any feedback or suggestions for improvements, please open an issue on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/issues). | |
| If you have any feedback or suggestions for improvements, please open a discussion on the [Node.js Userland Migrations repository](https://github.com/nodejs/userland-migrations/discussions). |
5 participants
Description
Reflect current status of the
userland-migrationinitiative. Plus show new codemods.Related Issues
No related issues
Check List
pnpm formatto ensure the code follows the style guide.pnpm testto check if all tests are passing.pnpm buildto check if the website builds without errors.