[pull] main from facebook:main

.github/workflows/publish.yml

@@ -29,6 +29,7 @@ on:
           - beta
           - rc
           - latest
+          - v3-stable
 
 permissions:
   id-token: write # For OIDC, see https://docs.npmjs.com/trusted-publishers

.github/workflows/security-supply-chain.yml

@@ -41,7 +41,7 @@ jobs:
 
       # Ensure our monorepo gets scanned by SFW
       - name: Install monorepo dependencies with SFW
-        run: sfw yarn install --frozen-lockfile
+        run: sfw yarn install --frozen-lockfile || sfw yarn install --frozen-lockfile || sfw yarn install --frozen-lockfile
 
       # Check for malicious lockfile injections
       # See https://github.com/lirantal/npm-security-best-practices#4-prevent-npm-lockfile-injection
@@ -55,7 +55,7 @@ jobs:
 
       # Ensure our init template gets scanned by SFW
       - name: Install test-website project with SFW
-        run: sfw yarn install --frozen-lockfile
+        run: sfw yarn install --frozen-lockfile || sfw yarn install --frozen-lockfile || sfw yarn install --frozen-lockfile
         working-directory: ../test-website
 
       # Ensure no unexpected lifecycle (preintall/postinstall scripts)
@@ -84,4 +84,4 @@ jobs:
 
           YAML
 
-          pnpm install
+          sfw pnpm install || sfw pnpm install || sfw pnpm install

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Docusaurus Changelog
 
+## 3.10.1 (2026-04-30)
+
+#### :bug: Bug Fix
+
+- `docusaurus-bundler`
+  - [#11981](https://github.com/facebook/docusaurus/pull/11981) fix(bundler): fix v3 webpackbar bug due to webpack breaking change ([@slorber](https://github.com/slorber))
+
+#### :wrench: Maintenance
+
+- `docusaurus`
+  - [#11982](https://github.com/facebook/docusaurus/pull/11982) chore: cherry-pick commits for v3.10.1 patch release ([@slorber](https://github.com/slorber))
+
+#### Committers: 1
+
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+
 ## 3.10.0 (2026-04-07)
 
 #### :rocket: New Feature

admin/new.docusaurus.io/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new.docusaurus.io",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "private": true,
   "scripts": {
     "start": "npx --package netlify-cli netlify dev"

admin/publish.md

@@ -15,6 +15,8 @@ For simplicity, usually don't maintain multiple major-version release lines in p
 
 However, we might occasionally have to backport critical bug and security fixes to a branch that could be cut on-demand. For major versions we usually create a `docusaurus-vX` branch once we have started merging breaking changes for the upcoming major version.
 
+---
+
 ## Publish a minor/major release
 
 We'll consider that the latest version is `3.10.0`, and we are now releasing `3.11.0`.
@@ -46,19 +48,82 @@ yarn build:website
 
 8. Create a PR ([example](https://github.com/facebook/docusaurus/pull/11825)). Make sure all CI checks pass. If useful, create it earlier to get a deploy preview to review.
 
-9. Go to the [Publish workflow](https://github.com/facebook/docusaurus/actions/workflows/publish.yml) and click the "Run workflow" button. Fill in the form with:
+9. Upgrade the `package.json` versions: `yarn lerna version 3.11.0 --exact --no-push --yes` (mostly useful for canary releases versions).
+
+10. Go to the [Publish workflow](https://github.com/facebook/docusaurus/actions/workflows/publish.yml) and click the "Run workflow" button. Fill in the form with:
 
-- From branch: main
-- NPM version: 3.10.0
-- NPM Dist tag: latest
+- From branch: `main`
+- NPM version: `3.10.0`
+- NPM Dist tag: `latest`
 
 10. Once the workflow finishes and code is on npm, you can merge the release PR.
 
 11. Follow the "After any release" section.
 
+---
+
 ## Release a patch
 
-TODO
+### Simple patch
+
+If you haven't merged any feature or breaking change on `main`, you can just follow the regular process above
+
+### Maintenance patch
+
+If you already merged features or breaking changes on `main`, you can't release a patch from `main` anymore and need to create a dedicated branch. We usually have protected `docusaurus-v<number>` maintenance branches for that reason (v3 is an exception, named `docusaurus-v3-maintenance` because `docusaurus-v3` was a mistake and I can't reset it).
+
+#### Feature merged on `main`
+
+If you want to release a fix for v3 while a feature has already been merged on `main`, you have 2 choices:
+
+- The fix waits for the next minor version
+- The fix is critical/urgent: you can update the `docusaurus-v<number>` branch, merge or backport the fix on this branch, and release from there
+
+#### Breaking change merged on `main`
+
+If a breaking change has already been merged on `main`, this means `main` is for the upcoming major version. If a patch is critical/urgent, you'll also want fix and/or backport it to the appropriate `docusaurus-v<number>` branch.
+
+#### How to backport a commit from `main`
+
+Cut a branch from `docusaurus-v<number>` and cherry pick commits to it, then open a PR and merge it.
+
+```bash
+git co docusaurus-v3-maintenance
+git pull
+git co -b slorber/v3.10.1-backports
+git cherry-pick <commit1>
+git cherry-pick <commit2>
+git cherry-pick <commit3>
+git push
+```
+
+#### Full example
+
+If you want to release `3.10.1` while `main` is already for `4.0.0`
+
+0. Make sure `docusaurus-v3-maintenance` is up to date. If not, upgrade it from the latest v3 release. The branch is protected so you need to use PRs.
+
+1. Backport/merge all the fixes for the patch release to `docusaurus-v3-maintenance` (using a PR, [example](https://github.com/facebook/docusaurus/pull/11982))
+
+2. Create a release branch from **main**: `git co main && git pull && git co -b slorber/release-v3.10.1`
+
+3. Rename the docs version from `3.10.0` to `3.10.1`
+
+4. Create the `3.10.1` changelog entry: `yarn changelog --from v3.10.0 --to docusaurus-v3-maintenance`
+
+5. Create a release PR that targets `main` ([example](https://github.com/facebook/docusaurus/pull/11983))
+
+6. Go to the [Publish workflow](https://github.com/facebook/docusaurus/actions/workflows/publish.yml) and click the "Run workflow" button. Fill in the form with:
+
+- From branch: `docusaurus-v3-maintenance` - ⚠️ Do not use `main`!
+- NPM version: `3.10.1`
+- NPM Dist tag: `latest` or `v3-stable` - ⚠️ Do not use `latest` if `4.0.0` is already out, use `v3-stable`
+
+7. Once the workflow finishes and code is on npm, you can merge the release PR in `main`.
+
+8. Follow the "After any release" section.
+
+---
 
 ## After any release
 

admin/test-bad-package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "test-bad-package",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "private": true,
   "dependencies": {
     "@mdx-js/react": "1.0.1",

argos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argos",
-  "version": "3.9.2",
+  "version": "3.10.1",
   "description": "Argos visual diff tests",
   "license": "MIT",
   "private": true,