diff --git a/admin/publish.md b/admin/publish.md new file mode 100644 index 000000000000..f4ea209d3835 --- /dev/null +++ b/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. diff --git a/website/blog/releases/3.10/index.mdx b/website/blog/releases/3.10/index.mdx index 5f6f2eeae4ff..9635b1dec7c1 100644 --- a/website/blog/releases/3.10/index.mdx +++ b/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`.