feat(README): Sync to nodejs/learn

.github/workflows/codemod_publish.yml

@@ -11,15 +11,21 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Tag to publish (format: v1.0.0@codemod-name)"
-        required: true
+        description: "Tag to publish (format: v1.0.0@codemod-name); ignored if sync_only"
+        required: false
         type: string
+      # For documentation-only changes, which warrant no version bump.
+      sync_only:
+        description: "Sync READMEs to nodejs/learn without publishing a codemod"
+        default: false
+        type: boolean
 
 permissions: read-all
 
 jobs:
   validate-and-publish:
     name: Validate and Publish Codemod
+    if: ${{ !inputs.sync_only }}
     runs-on: ubuntu-latest
 
     permissions:
@@ -139,3 +145,12 @@ jobs:
 
           ✅ Codemod has been successfully published to the registry!
           EOF
+
+  refresh-learn:
+    name: Sync nodejs/learn
+    needs: validate-and-publish
+    # Runs on its own when sync_only skipped the publish job above.
+    if: ${{ !cancelled() && (inputs.sync_only || needs.validate-and-publish.result == 'success') }}
+    uses: ./.github/workflows/refresh-learn.yml
+    secrets:
+      LEARN_REPO_TOKEN: ${{ secrets.LEARN_REPO_TOKEN }}

.github/workflows/refresh-learn.yml

@@ -0,0 +1,71 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Refresh nodejs/learn
+
+on:
+  workflow_call:
+    secrets:
+      LEARN_REPO_TOKEN:
+        required: true
+        description: >
+          Fine-grained PAT scoped to nodejs/learn with
+          Contents: write and Pull requests: write permissions.
+
+permissions:
+  contents: read
+
+concurrency:
+  group: refresh-learn
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    name: Sync READMEs to nodejs/learn
+    runs-on: ubuntu-slim
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout nodejs/learn
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: nodejs/learn
+          path: learn
+          token: ${{ secrets.LEARN_REPO_TOKEN }}
+          persist-credentials: false
+
+      - name: Checkout userland-migrations
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          path: source
+          persist-credentials: false
+
+      - name: Sync READMEs and update site.json
+        working-directory: learn
+        run: node ../source/scripts/sync-learn.mjs
+
+      - name: Open or update pull request on nodejs/learn
+        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
+        with:
+          path: learn
+          token: ${{ secrets.LEARN_REPO_TOKEN }}
+          add-paths: |
+            pages/userland-migrations
+            site.json
+          branch: automated/sync-userland-migrations
+          title: "chore: sync userland-migrations codemods"
+          commit-message: "chore: sync userland-migrations codemods"
+          body: |
+            Automated sync of codemod documentation from
+            [nodejs/userland-migrations](https://github.com/nodejs/userland-migrations).
+
+            Updates `pages/userland-migrations/` and `site.json` with the
+            latest README from every published recipe.
+
+            *This PR was automatically generated.*

CONTRIBUTING.md

@@ -30,7 +30,7 @@ Each codemod resides in its own directory under `recipes/` and should include:
 
 | File | Purpose |
 |------|---------|
-| `README.md` | Description, purpose, and usage instructions |
+| `README.md` | Description, purpose, and usage instructions — must follow the [README writing guide](./docs/writing-a-readme.md), as it is published as an article on [nodejs.org/learn](https://nodejs.org/learn) |
 | `package.json` | Package manifest |
 | `src/workflow.ts` | Main entry point using the `jssg` codemod API |
 | `codemod.yml` | Codemod manifest file |

README.md

@@ -39,3 +39,5 @@ You can find official Node.js codemods in the [Codemod Registry](https://codemod
 ## Acknowledgments
 
 We would like to extend our gratitude to the team at Codemod for providing their excellent tools and for their direct assistance with the Node.js project. Their support has been invaluable in making these migrations possible.
+
+<!-- sync_to_learn: false -->