ci(docs): build on PRs and pin Node 22 (Qodo follow-up to #7640) (#7645)

* ci(docs): build on PRs and pin Node 22 (Qodo follow-up to #7640)

Qodo flagged two reliability gaps on the oxc-minify fix that landed in
#7640:

  1. The Deploy Docs to GitHub Pages workflow only ran on push to
     develop, so a PR that broke `pnpm run docs:build` was not caught
     until after merge — exactly how the dead-link regression in #7546
     escaped. Add a pull_request trigger that runs the same build but
     skips the deploy/upload steps via `if: github.event_name ==
     'push'`. Also include the workflow file itself in the path filter
     so changes to it are exercised on PR.
  2. oxc-minify@0.128.0 requires Node ^20.19.0 || >=22.12.0, but the
     workflow did not pin Node and the repo declared engines.node
     >=22.0.0 with engineStrict: true — a runner image (or local dev)
     on Node 22.0–22.11 would refuse to install. Pin Node 22 in the
     docs workflow with actions/setup-node@v6 (matching the rest of
     CI), and bump engines.node to >=22.12.0 so the project's
     engineStrict gate matches the actual minimum.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci(docs): split build and deploy so PR runs do not hit pages env protection

The previous attempt put `if: github.event_name == 'push'` on individual
deploy steps but kept the single job's `environment: github-pages`
binding. Environment protection rules reject any non-develop ref
(including `refs/pull/N/merge`), so the runner failed the entire job
at creation time before any step could execute:

    Branch "refs/pull/7645/merge" is not allowed to deploy to
    github-pages due to environment protection rules.

Split into two jobs: `build` runs on every trigger (PR + push) and
uploads the artifact only on push, `deploy` depends on `build`,
runs only on push, and is the only job bound to the github-pages
environment. Standard GHA pages-deploy pattern; PR builds never
attempt to enter the protected environment.

* docs: align Node minimum references with bumped engines.node (Qodo round 2 on #7645)

Qodo flagged that engines.node moved from >=22.0.0 to >=22.12.0 in
this PR but documentation still claimed the old requirement. Sync the
three places that pinned a specific minimum:

  - README.md installation requirements (>= 22 → >= 22.12)
  - doc/npm-trusted-publishing.md publish prerequisites
    (>=22.0.0 → >=22.12.0, with oxc-minify cited as the driver)
  - CHANGELOG.md 2.7.3 breaking-changes entry (22 → 22.12, with the
    same oxc-minify justification)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: JohnMcLear

.github/workflows/build-and-deploy-docs.yml

@@ -1,34 +1,38 @@
-# Workflow for deploying static content to GitHub Pages
+# Workflow for building and deploying the VitePress site to GitHub Pages.
+# Build runs on every push to develop and on every PR that touches docs (so
+# a build regression is caught at review time instead of breaking develop
+# after merge — see #7640). Deploy runs only on push: the github-pages
+# environment has protection rules that reject PR refs, and a PR build
+# never produced an artifact to deploy anyway.
 name: Deploy Docs to GitHub Pages
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["develop"]
     paths:
-      - doc/** # Only run workflow when changes are made to the doc directory
-  # Allows you to run this workflow manually from the Actions tab
+      - doc/**
+      - .github/workflows/build-and-deploy-docs.yml
+  pull_request:
+    paths:
+      - doc/**
+      - .github/workflows/build-and-deploy-docs.yml
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
   packages: read
 
-# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
-# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and latest queued. Do NOT cancel in-progress runs — production
+# deployments are allowed to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
-  # Single deploy job since we're just deploying
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+  build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -52,20 +56,44 @@ jobs:
         with:
           version: 10.33.2
           run_install: false
+      # Pin Node so the build does not silently fall back to whatever the
+      # runner image ships with. oxc-minify (a vitepress peer when
+      # rolldown-vite is in use) requires Node ^20.19.0 || >=22.12.0; the
+      # repo declares engines.node >=22.12.0 to match.
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          cache: pnpm
       - name: Setup Pages
+        if: github.event_name == 'push'
         uses: actions/configure-pages@v6
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Build app
         working-directory: doc
         run: pnpm run docs:build
         env:
+          GITHUB_PAGES: ${{ github.event_name == 'push' && 'true' || '' }}
           COMMIT_REF: ${{ github.sha }}
       - name: Upload artifact
+        if: github.event_name == 'push'
         uses: actions/upload-pages-artifact@v5
         with:
-          # Upload entire repository
           path: './doc/.vitepress/dist'
+
+  # Deploy to GitHub Pages on push to develop only. Kept as a separate job
+  # because the github-pages environment's protection rules reject any
+  # non-develop ref (including PR merge refs), which used to fail the entire
+  # workflow at job-creation time before any build step could run.
+  deploy:
+    needs: build
+    if: github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v5

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ### Breaking changes
 
-- **Minimum required Node.js version is now 22.** Node.js 20 is reaching end-of-life (see https://nodejs.org/en/about/previous-releases). The CI matrix now targets Node 22, 24, and 25. Upgrading should be straightforward — install a current Node.js release before updating Etherpad.
+- **Minimum required Node.js version is now 22.12.** Node.js 20 is reaching end-of-life (see https://nodejs.org/en/about/previous-releases) and the docs build's `oxc-minify` peer requires `^20.19.0 || >=22.12.0`. The CI matrix now targets Node 22, 24, and 25. Upgrading should be straightforward — install a current Node.js release before updating Etherpad.
 
 ### Notable enhancements
 

README.md

@@ -160,7 +160,7 @@ volumes:
 
 ### Requirements
 
-[Node.js](https://nodejs.org/) >= 22.
+[Node.js](https://nodejs.org/) >= 22.12.
 
 ### Windows, macOS, Linux
 

doc/npm-trusted-publishing.md

@@ -85,9 +85,10 @@ If a package previously had an `NPM_TOKEN` secret in CI:
 
 ## Requirements
 
-- **Node.js**: >= 22 on the runner. npm 11 requires `>=22.9.0`, which
-  `setup-node@v6 with version: 22` satisfies (resolves to the latest 22.x).
-  The project's `engines.node` requires `>=22.0.0`.
+- **Node.js**: >= 22.12 on the runner. npm 11 requires `>=22.9.0` and
+  `oxc-minify` (a vitepress peer for the docs build) requires `>=22.12.0`,
+  both of which `setup-node@v6 with version: 22` satisfies (resolves to the
+  latest 22.x). The project's `engines.node` requires `>=22.12.0`.
 - **npm CLI**: >= 11.5.1. The publish workflow runs `npm install -g npm@latest`
   before publishing so the bundled npm version doesn't matter.
 - **Runner**: must be a GitHub-hosted (cloud) runner. Self-hosted runners are

package.json

@@ -42,7 +42,7 @@
     "ui": "link:ui"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "repository": {
     "type": "git",