From d84ed160471633b92dc588716139f82d2390639d Mon Sep 17 00:00:00 2001 From: sebastien Date: Thu, 12 Nov 2026 22:22:51 +0100 Subject: [PATCH 1/3] ci: reproduce the build hang when only the server persistent cache is invalid Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build-persistent-cache.yml | 41 ++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .github/workflows/build-persistent-cache.yml diff --git a/.github/workflows/build-persistent-cache.yml b/.github/workflows/build-persistent-cache.yml new file mode 100644 index 000000000000..65bce7b1b3aa --- /dev/null +++ b/.github/workflows/build-persistent-cache.yml @@ -0,0 +1,41 @@ +name: Build Persistent Cache + +on: + pull_request: + branches: + - main + - docusaurus-v** + paths: + - packages/** + - .github/workflows/build-persistent-cache.yml + +concurrency: + group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + build: + name: Build Persistent Cache + timeout-minutes: 30 + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - name: Set up pnpm, Node.js and dependencies + uses: $/.github/actions/setup + with: + cache: true + - name: Build with a cold cache + run: pnpm build:website:fast + - name: Build with a warm client cache and a cold server cache + # Another server Node.js target only evicts the server cache, like a Node.js upgrade + # See https://github.com/meta/docusaurus/pull/PR_NUMBER + run: pnpm build:website:fast + timeout-minutes: 5 + env: + DOCUSAURUS_SERVER_NODE_TARGET: 24.0.0 From 5d8a91db63d562cf56513b2fa7dc39bdfe43cb98 Mon Sep 17 00:00:00 2001 From: sebastien Date: Thu, 12 Nov 2026 22:23:20 +0100 Subject: [PATCH 2/3] ci: link the repro PR Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build-persistent-cache.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build-persistent-cache.yml b/.github/workflows/build-persistent-cache.yml index 65bce7b1b3aa..bcb9417271d0 100644 --- a/.github/workflows/build-persistent-cache.yml +++ b/.github/workflows/build-persistent-cache.yml @@ -34,7 +34,7 @@ jobs: run: pnpm build:website:fast - name: Build with a warm client cache and a cold server cache # Another server Node.js target only evicts the server cache, like a Node.js upgrade - # See https://github.com/meta/docusaurus/pull/PR_NUMBER + # See https://github.com/meta/docusaurus/pull/13034 run: pnpm build:website:fast timeout-minutes: 5 env: From c0bde38a7f2f65177505ace5d50885a7d99ae634 Mon Sep 17 00:00:00 2001 From: sebastien Date: Thu, 12 Nov 2026 22:45:04 +0100 Subject: [PATCH 3/3] test(core): replace the repro workflow with a unit test A cache version test captures the cause of the hang (the client cache is kept when only the server target changes), without an extra CI workflow. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build-persistent-cache.yml | 41 ------------------- .../src/webpack/__tests__/base.test.ts | 10 +++++ 2 files changed, 10 insertions(+), 41 deletions(-) delete mode 100644 .github/workflows/build-persistent-cache.yml diff --git a/.github/workflows/build-persistent-cache.yml b/.github/workflows/build-persistent-cache.yml deleted file mode 100644 index bcb9417271d0..000000000000 --- a/.github/workflows/build-persistent-cache.yml +++ /dev/null @@ -1,41 +0,0 @@ -name: Build Persistent Cache - -on: - pull_request: - branches: - - main - - docusaurus-v** - paths: - - packages/** - - .github/workflows/build-persistent-cache.yml - -concurrency: - group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} - cancel-in-progress: true - -permissions: - contents: read - -jobs: - build: - name: Build Persistent Cache - timeout-minutes: 30 - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - persist-credentials: false - - name: Set up pnpm, Node.js and dependencies - uses: $/.github/actions/setup - with: - cache: true - - name: Build with a cold cache - run: pnpm build:website:fast - - name: Build with a warm client cache and a cold server cache - # Another server Node.js target only evicts the server cache, like a Node.js upgrade - # See https://github.com/meta/docusaurus/pull/13034 - run: pnpm build:website:fast - timeout-minutes: 5 - env: - DOCUSAURUS_SERVER_NODE_TARGET: 24.0.0 diff --git a/packages/docusaurus/src/webpack/__tests__/base.test.ts b/packages/docusaurus/src/webpack/__tests__/base.test.ts index 887e0902e4c1..279a387deda9 100644 --- a/packages/docusaurus/src/webpack/__tests__/base.test.ts +++ b/packages/docusaurus/src/webpack/__tests__/base.test.ts @@ -232,6 +232,16 @@ describe('base webpack config', () => { expect(oldNodeVersion).not.toBe(newNodeVersion); }); + // TODO a warm client cache with a cold server cache hangs the build + // See https://github.com/meta/docusaurus/pull/13034 + it('keeps the client cache when the server Node.js target changes', async () => { + stubServerNodeTarget('24.11.1'); + const oldNodeVersion = await getCacheVersion({isServer: false}); + stubServerNodeTarget('24.11.2'); + const newNodeVersion = await getCacheVersion({isServer: false}); + expect(oldNodeVersion).toBe(newNodeVersion); + }); + it('is evicted when a plugin package version changes', async () => { const oldPluginVersion = await getCacheVersion({ siteMetadata: createSiteMetadata({pluginVersion: '1.0.0'}),