feat(README): Sync to `nodejs/learn` by avivkeller · Pull Request #423 · nodejs/userland-migrations

avivkeller · 2026-04-06T16:57:04Z

This PR does two things:

It rewrites all READMEs to conform to a new docs/writing-a-readme.md guide, which explains how to write the README so it appears like a good article on nodejs.org/learn
Adds a CI/CD action to update learn

Copilot

Pull request overview

This PR standardizes recipe documentation so each recipe README reads like a consistent article (intended for nodejs.org/learn), and starts wiring CI/CD to trigger a downstream refresh in nodejs/learn after publishing.

Changes:

Rewrites many recipes/*/README.md files to follow a shared structure (frontmatter, Usage, Examples, optional Notes/Limitations).
Adds docs/writing-a-readme.md documenting the required README template and conventions.
Extends the publish workflow to trigger a refresh workflow in nodejs/learn after a successful publish.

Reviewed changes

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

Show a summary per file

File	Description
recipes/zlib-bytesread-to-byteswritten/README.md	Reformats recipe README into the new article-style template with usage + examples.
recipes/util-print-to-console-log/README.md	Rewrites README to structured format and expands examples per import style.
recipes/util-log-to-console-log/README.md	Rewrites README to structured format and adds multiple examples.
recipes/util-is/README.md	Rewrites README with a replacement table and structured usage/examples.
recipes/util-extend-to-object-assign/README.md	Rewrites README with multiple import-style examples and usage section.
recipes/types-is-native-error/README.md	Rewrites README with structured examples for multiple call/import patterns.
recipes/tmpdir-to-tmpdir/README.md	Rewrites README to structured template (but Usage command currently incorrect).
recipes/tls-create-secure-pair-to-tls-socket/README.md	Rewrites README with clearer mapping notes and structured examples.
recipes/timers-deprecations/README.md	Rewrites README with multiple examples covering each deprecated timers API.
recipes/slow-buffer-to-buffer-alloc-unsafe-slow/README.md	Rewrites README with structured examples for CJS/ESM patterns.
recipes/rmdir/README.md	Rewrites README to structured template and clarifies transformation scope.
recipes/repl-classes-with-new/README.md	Rewrites README with structured usage and CJS/ESM examples.
recipes/repl-builtin-modules/README.md	Rewrites README with structured usage and examples for require/import cases.
recipes/process-main-module/README.md	Rewrites README with structured examples for multiple access patterns.
recipes/process-assert-to-node-assert/README.md	Rewrites README and clarifies behavior re: module type detection and reuse of existing imports.
recipes/node-url-to-whatwg-url/README.md	Rewrites README to structured template and documents property-mapping nuances.
recipes/mock-module-exports/README.md	Rewrites README to structured template with multiple option-shape examples.
recipes/import-assertions-to-attributes/README.md	Rewrites README with structured examples (but title currently doesn’t match naming guidance).
recipes/http-outgoingmessage-headers/README.md	Adds new canonical README.md for the recipe in the new template format.
recipes/http-outgoingmessage-headers/readme.md	Removes old non-canonical lowercase readme file.
recipes/http-classes-with-new/README.md	Rewrites README with structured examples for namespace + named imports.
recipes/fs-truncate-fd-deprecation/README.md	Rewrites README with structured usage, examples, and limitations notes.
recipes/fs-access-mode-constants/README.md	Rewrites README with structured examples across require/import styles.
recipes/dirent-path-to-parent-path/README.md	Rewrites README with structured examples for loops, callbacks, and destructuring.
recipes/crypto-rsa-pss-update/README.md	Rewrites README with structured examples and a limitations note.
recipes/crypto-fips-to-getFips/README.md	Rewrites README with structured examples for read/write scenarios.
recipes/crypto-createcipheriv-migration/README.md	Rewrites README with structured examples and notes explaining required manual review.
recipes/createCredentials-to-createSecureContext/README.md	Rewrites README to structured template (but Usage command currently doesn’t match published package name).
recipes/create-require-from-path/README.md	Rewrites README with structured examples including aliased import case.
recipes/correct-ts-specifiers/README.md	Rewrites README to shorter structured form with a single consolidated diff example + limitations note.
recipes/chalk-to-util-styletext/README.md	Rewrites README with structured examples and limitations note (but title is not very descriptive).
recipes/buffer-atob-btoa/README.md	Rewrites README with structured examples and notes about import removal behavior.
docs/writing-a-readme.md	Introduces the canonical README writing guide and mandatory template.
.github/workflows/codemod_publish.yml	Adds a post-publish job to trigger a refresh workflow in `nodejs/learn`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-06T17:03:28Z

+Run this codemod with:
+
+```sh
+npx codemod @nodejs/tmpDir-to-tmpdir


The npx codemod command uses @nodejs/tmpDir-to-tmpdir, but the published package name is all-lowercase (@nodejs/tmpdir-to-tmpdir, per this recipe’s package.json). As written, npx will fail to resolve the package on npm. Update the Usage command to the correct package name (lowercase).

Suggested change

npx codemod @nodejs/tmpDir-to-tmpdir

npx codemod @nodejs/tmpdir-to-tmpdir

Copilot · 2026-04-06T17:03:28Z

+Run this codemod with:
+
+```sh
+npx codemod @nodejs/createCredentials-to-createSecureContext


The Usage command uses @nodejs/createCredentials-to-createSecureContext, but npm package names must be lowercase and this recipe’s package.json declares the published name as @nodejs/createcredentials-to-createsecurecontext. Using the current command will fail. Please update the command to match the actual package name.

Suggested change

npx codemod @nodejs/createCredentials-to-createSecureContext

npx codemod @nodejs/createcredentials-to-createsecurecontext

Copilot · 2026-04-06T17:03:29Z

+Run this codemod with:
+
+```sh
+npx codemod @nodejs/<recipe-directory-name>
+```


The mandatory template says to run recipes using npx codemod @nodejs/<recipe-directory-name>, but npm package names must be lowercase and may not match a directory name if the directory contains uppercase (e.g., recipes/createCredentials-to-createSecureContext publishes as @nodejs/createcredentials-to-createsecurecontext). Consider updating the guidance to reference the package name from the recipe’s package.json (or explicitly require lowercase directory names that match the package name).

Copilot · 2026-04-06T17:03:29Z

+---

-This recipe converts import assertions (`assert` syntax) to the standardized import attributes (`with` syntax). It modifies code like:
+# import assert import with


The title # import assert import with doesn’t follow the naming guidance in docs/writing-a-readme.md for non-deprecation migrations (use a plain descriptive title like “Import Assertions to Attributes”), and it’s ambiguous when rendered as an article heading. Please rename the title to a clearer, descriptive form consistent with the guide.

Suggested change

# import assert import with

# Import Assertions to Attributes

Copilot · 2026-04-06T17:03:29Z

+---

-This recipe migrates from the external `chalk` package to Node.js built-in `util.styleText` API. It transforms chalk method calls to use the native Node.js styling functionality.
+# chalk util.styleText


The title # chalk util.styleText is not very descriptive as an article heading and doesn’t match the title patterns in docs/writing-a-readme.md (non-deprecation migrations should use a plain descriptive title). Consider renaming it to something like “Chalk to util.styleText” (or similar) to match the convention and improve readability on nodejs.org/learn.

Suggested change

# chalk util.styleText

# Chalk to util.styleText

Suggested change

# chalk util.styleText

# Chalk to `util.styleText()`

JakobJingleheimer

Awesome, thanks for this! I'm slowly making my way through it (6/36 so far).

JakobJingleheimer

Btw, let's include patch version bumps for each migration so the published README matches what'll be in Learn.

JakobJingleheimer · 2026-04-07T16:36:43Z

+---

-This recipe migrates from the external `chalk` package to Node.js built-in `util.styleText` API. It transforms chalk method calls to use the native Node.js styling functionality.
+# chalk util.styleText


Suggested change

# chalk util.styleText

# Chalk to `util.styleText()`

JakobJingleheimer · 2026-04-27T09:15:56Z

READMEs to conform to a new docs/writing-a-readme.md guide

Should we add a markdown validation workflow to ensure new READMEs conform? Perhaps we could leverage mdvalidator.

avivkeller · 2026-04-27T15:54:02Z

Sure! To be honest, however, this is kinda on hold until we get a token

JakobJingleheimer · 2026-04-27T16:04:53Z

Plus it's huge, so it takes a while to review 😅

avivkeller · 2026-08-07T17:22:07Z

Still waiting for a token, btw

AugustinMauroy · 2026-08-09T20:08:09Z

also after re-read with new discussion I realized that all codemod will have dedicated page. right ?
that not seem good idea since some of theme is just one deprecation.

maybe having a json with list of coemod that can be synced

avivkeller · 2026-08-09T20:09:25Z

oh! we got the token a while ago, let me rebase and merge

Signed-off-by: Aviv Keller <me@aviv.sh>

Copilot AI review requested due to automatic review settings April 6, 2026 16:57

Copilot started reviewing on behalf of avivkeller April 6, 2026 16:57 View session

avivkeller added the blocked:upstream Depends on another PR or external change/fix label Apr 6, 2026

Copilot AI reviewed Apr 6, 2026

View reviewed changes

avivkeller mentioned this pull request Apr 6, 2026

Request token for nodejs/userland-migrations nodejs/admin#1055

Merged

JakobJingleheimer reviewed Apr 7, 2026

View reviewed changes

avivkeller removed the blocked:upstream Depends on another PR or external change/fix label Jul 11, 2026

AugustinMauroy reviewed Aug 7, 2026

View reviewed changes

Comment thread .github/workflows/refresh-learn.yml Outdated

AugustinMauroy reviewed Aug 9, 2026

View reviewed changes

Comment thread recipes/chalk-to-util-styletext/README.md

avivkeller force-pushed the learn branch from 3ca5484 to b506300 Compare August 9, 2026 20:30

avivkeller requested review from AugustinMauroy and JakobJingleheimer August 9, 2026 20:37

AugustinMauroy reviewed Aug 9, 2026

View reviewed changes

Comment thread recipes/correct-ts-specifiers/.codemodrc.json

AugustinMauroy approved these changes Aug 9, 2026

View reviewed changes

feat(README): prep for learn

da7cf08

avivkeller force-pushed the learn branch from 2ed4286 to da7cf08 Compare August 9, 2026 20:51

feat(README): learn syncing

74a5867

Signed-off-by: Aviv Keller <me@aviv.sh>

avivkeller merged commit aedfc76 into main Aug 9, 2026
3 checks passed

avivkeller deleted the learn branch August 9, 2026 20:54

	npx codemod @nodejs/tmpDir-to-tmpdir
	npx codemod @nodejs/tmpdir-to-tmpdir

	npx codemod @nodejs/createCredentials-to-createSecureContext
	npx codemod @nodejs/createcredentials-to-createsecurecontext

	# import assert import with
	# Import Assertions to Attributes

Uh oh!

Uh oh!

Conversation

avivkeller commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 6, 2026

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

JakobJingleheimer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JakobJingleheimer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JakobJingleheimer Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JakobJingleheimer commented Apr 27, 2026

Uh oh!

avivkeller commented Apr 27, 2026

Uh oh!

JakobJingleheimer commented Apr 27, 2026

Uh oh!

Uh oh!

avivkeller commented Aug 7, 2026

Uh oh!

AugustinMauroy commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avivkeller commented Aug 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

avivkeller commented Apr 6, 2026 •

edited

Loading

AugustinMauroy commented Aug 9, 2026 •

edited

Loading