chore: update release instructions + minor post-v3.10 release updates (#11913)

Author: slorber

admin/publish.md

@@ -0,0 +1,97 @@
+# Publishing Instructions
+
+These instructions have been updated on April 2026, after the [adoption of npm Trusted Publishing](https://docusaurus.io/blog/releases/3.10#trusted-publishing) in v3.10 ([PR](https://github.com/facebook/docusaurus/pull/11819)).
+
+This guide is designed to be a very concise overview. Read the [publish-legacy.md](./publish-legacy.md) guide for more details, many steps remain the same, and it provides more details.
+
+---
+
+## General
+
+For simplicity, usually don't maintain multiple major-version release lines in parallel:
+
+- new features and breaking changes are always merged on main
+- we only merge breaking changes once we are ready to release the next major version
+
+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`.
+
+Using npm Trusted Publishing, our releases are published from the `.deploy.yml` GitHub action directly from the `main` branch. Make sure that branch works well and pass all of our CI tests.
+
+However, we need a release branch to cut the new docs version, publish a release blog post and update our changelog.
+
+1. Create a release branch: `git co -b slorber/release-3.11.0`
+
+2. Make sure all the recent PRs have a `pr: ` GitHub label. This [link](https://github.com/facebook/docusaurus/pulls?q=is%3Apr+is%3Amerged+sort%3Aupdated-desc+-label%3A%22pr%3A+breaking+change%22%2C%22pr%3A+new+feature%22%2C%22pr%3A+bug+fix%22%2C%22pr%3A+performance%22%2C%22pr%3A+polish%22%2C%22pr%3A+documentation%22%2C%22pr%3A+maintenance%22%2C%22pr%3A+internal%22%2C%22pr%3A+dependencies%22%2C%22pr%3A+showcase%22%2C%22pr%3A+ignore%22%2C%22pr%3A+translations%22+) helps you find untagged PRs.
+
+3. Run `yarn changelog --from v3.10.0` to generate a changelog from the tagged PRs since a given release/tag.
+
+4. Copy that at the top of the `CHANGELOG.md` file with title `## 3.11.0 (date)`.
+
+5. Write a release blog post, inspired by former release posts.
+
+6. Create the docs version: `yarn workspace website docusaurus docs:version 3.11.0`
+
+7. Make sure there's no Crowdin translation problem. Run this:
+
+```bash
+yarn workspace website write-translations
+yarn crowdin:upload:website
+yarn crowdin:download:website
+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:
+
+- 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
+
+## After any release
+
+### Update the examples
+
+Do this on a separate branch/PR after a major/minor/patch release:
+
+```bash
+git co -b slorber/release-v3.11.0-examples
+yarn examples:generate
+git push
+```
+
+Open the PR, then merge it.
+
+Make sure the [Docusaurus Playground](https://docusaurus.new) sandboxes keeps working.
+
+### Publish the GitHub release
+
+- Go to https://github.com/facebook/docusaurus/releases/new
+- Use tag `v3.11.0`
+- Use title `3.11.0`
+- Paste the release changelog
+- Check "Create a discussion for this release", use type "Release feedback"
+- Publish
+
+### Marketing
+
+Post about the new release on:
+
+- X - [example](https://x.com/sebastienlorber/status/2041532494076371044)
+- Bluesky - [example](https://bsky.app/profile/did:plc:hxmev3uady7j4litwnr5fzbg/post/3miw5wx5kck2t)
+- LinkedIn - [example](https://www.linkedin.com/posts/sebastienlorber_docusaurus-310-is-out-a-milestone-release-share-7447314350014517248-u2LR?utm_source=share&utm_medium=member_desktop&rcm=ACoAAASnHqkBaWvOyS4Hb4oFczVnrE8AA7RA6pU)
+- Discord #announcements channel - [example](https://discord.com/channels/398180168688074762/867060988717301780/1491091672250191963)
+
+It's not always easy to get access to an official [@docusaurus](https://x.com/docusaurus) account, but marketing is important, so at least publish something under your own name/account.

website/blog/releases/3.10/index.mdx

@@ -8,6 +8,8 @@ date: 2026-04-07
 
 We are happy to announce **Docusaurus 3.10**.
 
+This will be the **last release in the v3.x line**, and it helps you **prepare for Docusaurus v4**.
+
 Upgrading is easy. We follow [Semantic Versioning](https://semver.org/), and minor version updates have **no breaking changes**, according to our [release process](/community/release-process).
 
 However, if you opt in for upcoming Docusaurus v4 breaking changes globally with `future.v4: true`, make sure to review the dedicated section below.
@@ -20,7 +22,7 @@ However, if you opt in for upcoming Docusaurus v4 breaking changes globally with
 import BrowserWindow from '@site/src/components/BrowserWindow';
 ```
 
-## v4 future flags {/* #v4-future-flags */}
+## v4 Future Flags {/* #v4-future-flags */}
 
 The [Docusaurus v4 Future Flags](/docs/api/docusaurus-config#future) let you **opt in for upcoming Docusaurus v4 breaking changes** incrementally and prepare for Docusaurus v4 ahead of time. You can enable them all at once with `future.v4: true`.