Merge branch 'develop'

Author: Etherpad Release Bot

.github/workflows/backend-tests.yml

@@ -66,24 +66,7 @@ jobs:
         run: pnpm build
       -
         name: Run the backend tests
-        env:
-          # --report-on-fatalerror and friends write a Node diagnostic report
-          # (V8 stack, libuv handles, OS info) on fatal errors that bypass JS
-          # handlers — the failure mode we've been chasing on Windows + Node
-          # 24 since PR #7663. Reports land in node-report/ and are uploaded
-          # as an artifact if the step fails.
-          NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
-        run: |
-          mkdir -p "${{ github.workspace }}/node-report"
-          pnpm test
-      - name: Upload Node diagnostic reports on failure
-        if: ${{ failure() }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: node-diagnostic-report-${{ runner.os }}-node${{ matrix.node }}-${{ github.job }}
-          path: node-report/
-          if-no-files-found: ignore
-          retention-days: 7
+        run: pnpm test
       - name: Run the new vitest tests
         working-directory: src
         run: pnpm run test:vitest
@@ -153,19 +136,7 @@ jobs:
           ep_table_of_contents
       -
         name: Run the backend tests
-        env:
-          NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
-        run: |
-          mkdir -p "${{ github.workspace }}/node-report"
-          pnpm test
-      - name: Upload Node diagnostic reports on failure
-        if: ${{ failure() }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: node-diagnostic-report-${{ runner.os }}-node${{ matrix.node }}-${{ github.job }}
-          path: node-report/
-          if-no-files-found: ignore
-          retention-days: 7
+        run: pnpm test
       - name: Run the new vitest tests
         working-directory: src
         run: pnpm run test:vitest
@@ -180,7 +151,18 @@ jobs:
       fail-fast: false
       matrix:
         # Etherpad requires Node >= 24 (see package.json engines.node).
-        node: ${{ fromJSON('[24]') }}
+        # Windows pins Node 24.16.0, not the runner-default 24.15.0. Node 24.15.0's
+        # bundled libuv (1.51.0) has a stack buffer overrun in the Windows TCP-connect
+        # path (uv__tcp_connect), proven by a /GS __fastfail full-memory dump under the
+        # backend suite's heavy localhost connection churn -- the long-standing Windows
+        # backend silent-ELIFECYCLE flake (memory corruption, so no JS/Node
+        # observability). Bisect: 24.15.0 crashes (4/4 on 127.0.0.1), 24.16.0
+        # (libuv 1.52.1) is clean (0/8). Stays on the 24 LTS line. Pin explicitly
+        # because setup-node's default check-latest:false reuses the runner's
+        # pre-cached 24.15.0 for a bare "24".
+        # Tracking: https://github.com/nodejs/node/issues/63620 — drop this pin
+        # back to plain "24" once the fix is across the supported 24.x baseline.
+        node: ${{ fromJSON('["24.16.0"]') }}
     name: Windows without plugins
     runs-on: windows-latest
     steps:
@@ -218,23 +200,9 @@ jobs:
         name: Run the backend tests
         shell: bash
         working-directory: src
-        env:
-          NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
-        run: |
-          mkdir -p "${{ github.workspace }}/node-report"
-          # --exit forces process.exit(failures) after the suite completes,
-          # closing the post-suite event-loop drain window where Windows +
-          # Node 24 hard-kills the process. Scoped to Windows so Linux/local
-          # runs still surface real handle leaks via natural drain.
-          pnpm test -- --exit
-      - name: Upload Node diagnostic reports on failure
-        if: ${{ failure() }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: node-diagnostic-report-${{ runner.os }}-node${{ matrix.node }}-${{ github.job }}
-          path: node-report/
-          if-no-files-found: ignore
-          retention-days: 7
+        # --exit makes mocha call process.exit() after the run so a leaked handle
+        # cannot hang the job on Windows.
+        run: pnpm test -- --exit
       - name: Run the new vitest tests
         working-directory: src
         run: pnpm run test:vitest
@@ -248,7 +216,18 @@ jobs:
       fail-fast: false
       matrix:
         # Etherpad requires Node >= 24 (see package.json engines.node).
-        node: ${{ fromJSON('[24]') }}
+        # Windows pins Node 24.16.0, not the runner-default 24.15.0. Node 24.15.0's
+        # bundled libuv (1.51.0) has a stack buffer overrun in the Windows TCP-connect
+        # path (uv__tcp_connect), proven by a /GS __fastfail full-memory dump under the
+        # backend suite's heavy localhost connection churn -- the long-standing Windows
+        # backend silent-ELIFECYCLE flake (memory corruption, so no JS/Node
+        # observability). Bisect: 24.15.0 crashes (4/4 on 127.0.0.1), 24.16.0
+        # (libuv 1.52.1) is clean (0/8). Stays on the 24 LTS line. Pin explicitly
+        # because setup-node's default check-latest:false reuses the runner's
+        # pre-cached 24.15.0 for a bare "24".
+        # Tracking: https://github.com/nodejs/node/issues/63620 — drop this pin
+        # back to plain "24" once the fix is across the supported 24.x baseline.
+        node: ${{ fromJSON('["24.16.0"]') }}
     name: Windows with Plugins
     runs-on: windows-latest
 
@@ -315,23 +294,9 @@ jobs:
         name: Run the backend tests
         shell: bash
         working-directory: src
-        env:
-          NODE_OPTIONS: "--report-on-fatalerror --report-uncaught-exception --report-on-signal --report-compact --report-directory=${{ github.workspace }}/node-report"
-        run: |
-          mkdir -p "${{ github.workspace }}/node-report"
-          # --exit forces process.exit(failures) after the suite completes,
-          # closing the post-suite event-loop drain window where Windows +
-          # Node 24 hard-kills the process. Scoped to Windows so Linux/local
-          # runs still surface real handle leaks via natural drain.
-          pnpm test -- --exit
-      - name: Upload Node diagnostic reports on failure
-        if: ${{ failure() }}
-        uses: actions/upload-artifact@v7
-        with:
-          name: node-diagnostic-report-${{ runner.os }}-node${{ matrix.node }}-${{ github.job }}
-          path: node-report/
-          if-no-files-found: ignore
-          retention-days: 7
+        # --exit makes mocha call process.exit() after the run so a leaked handle
+        # cannot hang the job on Windows.
+        run: pnpm test -- --exit
       - name: Run the new vitest tests
         working-directory: src
         run: pnpm run test:vitest

.pr_agent.toml

@@ -211,6 +211,38 @@ pnpm run plugins ls                     # List installed
 ### Settings
 Configured via `settings.json`. A template is available at `settings.json.template`. Environment variables can override any setting using `"${ENV_VAR}"` or `"${ENV_VAR:default_value}"`.
 
+## Releasing
+
+Releases are driven almost entirely by GitHub Actions. A maintainer dispatches **one** workflow; the version bump, tagging, GitHub Release, Docker images, and snap all cascade off the pushed tag. The npm publish is a separate manual dispatch.
+
+### Prerequisites (check these before dispatching)
+- **A `# X.Y.Z` changelog section for the _target_ version must already be at the top of `CHANGELOG.md`.** `bin/release.ts` aborts with `No changelog record for X.Y.Z, please create changelog record` if it's missing. Write the section before dispatching.
+- **All four `package.json` files must agree on the current version:** root `package.json`, `src/package.json`, `admin/package.json`, `bin/package.json`. `release.ts` reads the *current* version from **`src/package.json`** and computes the next with `semver.inc(current, type)`. If the files are out of sync (e.g. one was hand-edited), the computed target is wrong and the changelog guard fails. *(This exact desync — `src`/`bin` left at 3.3.0 while root/admin were 3.2.0 — blocked the 3.3.0 release in June 2026.)*
+
+### Cutting a release
+1. **Actions → "Release etherpad"** → Run workflow (`workflow_dispatch`), choose `patch` / `minor` / `major`. Cadence is monthly **minors** (3.0.0 → 3.1.0 → 3.2.0 → …); use `major` only for breaking changes.
+2. The **Prepare release** step runs `bin/release.ts`, which:
+   - sanity-checks the tree (clean working dir, on `develop`, `develop`/`master` upstreams in sync, `../ether.github.com` cloned & clean on `master`);
+   - bumps the version in all four `package.json` files;
+   - commits `bump version`, merges `develop` → `master`, creates both `X.Y.Z` **and** `vX.Y.Z` tags, merges `master` back to `develop`;
+   - builds and stages the versioned docs into the website repo (see **Documentation** below).
+3. The **Push after release** step (`bin/push-after-release.sh`) pushes `master`, `develop`, the tag, `--tags`, and the `ether.github.com` docs commit.
+4. The pushed **`vX.Y.Z` tag auto-triggers** three workflows:
+   - `handleRelease.yml` → builds Etherpad, extracts the matching changelog section via `generateChangelog` (`bin/generateReleaseNotes.ts`), and publishes the **GitHub Release** (`make_latest: true`);
+   - `docker.yml` → builds & pushes the Docker images;
+   - `snap-publish.yml` → publishes the snap.
+5. **npm publish is a separate manual step:** dispatch **"releaseEtherpad.yaml"** (`workflow_dispatch`), which runs `npm publish --provenance --access public` via npm **OIDC trusted publishing**. It is *not* fired by the tag.
+
+### Documentation
+
+Two distinct things, both important:
+
+**1. Per-PR doc updates — your responsibility in every behaviour-change PR.**
+The `doc/` workspace holds the user/admin/API docs (Markdown + AsciiDoc). Whenever a PR changes API responses, CLI flags, settings keys, hooks, or error formats, update the relevant files in `doc/` **in the same PR** — don't defer it to release time. The HTTP API reference is `doc/api/http_api.{md,adoc}` (keep both in sync). Preview locally with `pnpm run makeDocs`.
+
+**2. Release-time versioned docs publishing — automated, no manual step.**
+During a release, `release.ts` runs `pnpm run makeDocs` (→ `bin/make_docs.ts`) to render `doc/` into `out/doc/`, then copies it into the sibling website repo at `../ether.github.com/public/doc/vX.Y.Z`, bumps that repo's version, and commits `X.Y.Z docs`; `push-after-release.sh` pushes it, publishing the versioned docs on etherpad.org. This requires `ether.github.com` checked out as a **sibling directory** — the **Release etherpad** workflow checks it out automatically. If you ever run `release.ts` by hand, clone it first: `cd .. && git clone git@github.com:ether/ether.github.com.git`.
+
 ## Monorepo Structure
 
 This project uses pnpm workspaces. The workspaces are: