docs: adjust the Docusaurus release process documentation to our new simpler process (#11181)

Co-authored-by: slorber <749374+slorber@users.noreply.github.com>

project-words.txt

@@ -183,7 +183,6 @@ navigations
 navlink
 netrc
 newtab
-ngryman
 Nisarag
 noflash
 noicon

website/blog/releases/3.0/index.mdx

@@ -28,7 +28,7 @@ The simplest sites will only need to upgrade a few npm dependencies. For more co
 
 :::info About Docusaurus v2
 
-According to our [release process](/community/release-process#stable-version), Docusaurus v2 has now entered **maintenance mode**. It will only receive support for major security issues for 3 months, until 31 January 2024. It is recommended to upgrade within that time frame to v3.
+According to our [release process](/community/release-process), Docusaurus v2 has now entered **maintenance mode**. It will only receive support for major security issues for 3 months, until 31 January 2024. It is recommended to upgrade within that time frame to v3.
 
 :::
 

website/community/4-canary.mdx

@@ -16,7 +16,7 @@ import {
 
 Docusaurus has a canary releases system.
 
-It permits you to **test new unreleased features** as soon as the pull requests are merged on the [next version](./5-release-process.mdx#next-version) of Docusaurus.
+It permits you to **test new unreleased features** as soon as the pull requests are merged.
 
 It is a good way to **give feedback to maintainers**, ensuring the newly implemented feature works as intended.
 

website/community/5-release-process.mdx

@@ -19,14 +19,6 @@ Respecting Semantic Versioning is important for multiple reasons:
 - A new major version is an opportunity to thoroughly document breaking changes
 - A new major/minor version is an opportunity to communicate new features through a blog post
 
-:::note
-
-Releasing Docusaurus 2.0 took a very long time. From now on, Docusaurus will **release new major versions more regularly**. In practice, you can expect a new major version every 2–4 months.
-
-[Major version numbers are not sacred](https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html), but we still group breaking changes together and avoid releasing major versions too often.
-
-:::
-
 ### Major versions {#major-versions}
 
 The `major` version number is incremented on **every breaking change**.
@@ -69,66 +61,36 @@ Whenever a new patch version is released, we publish:
 
 ```mdx-code-block
 import {
-  StableMajorVersion,
+  CurrentMajorVersionNumber,
-  NextMajorVersion,
   StableMajorBranchLink,
-  NextMajorBranchLink,
+  MainBranchLink,
 } from "@site/src/components/Versions";
 ```
 
-The Docusaurus team is usually working on 2 major versions at the same time:
+The Docusaurus team uses a simple development process and only works on a single major version and a single Git branch at a same time:
 
-- **Docusaurus <StableMajorVersion/>**: the **stable** version, on the <StableMajorBranchLink/> branch
+- **Docusaurus {CurrentMajorVersionNumber}**: the **stable** version, on the <MainBranchLink/> branch.
-- **Docusaurus <NextMajorVersion/>**: the **next** version, on the <NextMajorBranchLink/> branch
 
-:::note
+:::note How we will ship the next version
 
-The <StableMajorBranchLink/> branch is created just before releasing the first v<StableMajorVersion/> release candidate.
+Once we are ready ship **Docusaurus {CurrentMajorVersionNumber + 1}**, we will:
+
+- create a <StableMajorBranchLink/> branch
+- merge breaking changes on the <MainBranchLink/> branch
+- release that new version directly from the <MainBranchLink/> branch
 
 :::
 
-### Stable version {#stable-version}
+:::warning Security fixes policy
 
-The stable version (v<StableMajorVersion/>, on <StableMajorBranchLink/>) is recommended for most Docusaurus users.
+After a new stable version has been released, the former stable version will continue to receive support for **major security issues** for **3 months**.
 
-We regularly backport retro-compatible features, bug and security fixes from <NextMajorBranchLink/> to <StableMajorBranchLink/> with `git cherry-pick` to make them available to those not ready for the next version.
+In practice, we will backport security fixes to the <StableMajorBranchLink/> branch. Otherwise, all features will be frozen and non-critical bugs will not be fixed.
-
-:::info
-
-After a new stable version has been released, the former stable version will continue to receive support only for **major security issues** for **3 months**. Otherwise, all features will be frozen and non-critical bugs will not be fixed.
 
 It is recommended to upgrade within that time frame to the new stable version.
 
 :::
 
-### Next version {#next-version}
-
-The next version (v<NextMajorVersion/>, on <NextMajorBranchLink/>) is the version the Docusaurus team is currently working on.
-
-The <NextMajorBranchLink/> branch is the **default target branch** for all pull requests, including core team and external contributions.
-
-This version is recommended for **early adopters** that want to use the latest Docusaurus features as soon as possible. It is also a good way to help us by reporting bugs and giving some feedback.
-
-There are 3 ways to use the next version:
-
-- with an `alpha`, `beta` or `rc` pre-release
-- with the `@next` npm dist tag for the latest pre-release
-- with a [canary release](./4-canary.mdx) for the very latest features
-
-:::tip
-
-The next version passes all our automated tests and is used by the Docusaurus site itself. It is relatively safe: don't be afraid to give it a try.
-
-:::
-
-:::warning
-
-Breaking changes can happen on the next version: detailed upgrade instructions are available in the changelog and pull requests.
-
-At the `beta` and `rc` (release candidate) phases, we avoid introducing major breaking changes.
-
-:::
-
 ## Public API surface {#public-api-surface}
 
 Docusaurus commits to respecting Semantic Versioning. This means that whenever changes occur in Docusaurus public APIs and break backward compatibility, we will increment the `major` version number.

website/src/components/Versions.tsx

@@ -19,6 +19,12 @@ import {
 import Translate from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import CodeBlock from '@theme/CodeBlock';
+import versions from '@site/versions.json';
+
+export const CurrentMajorVersionNumber = parseInt(
+  versions[0]!.split('.')[0]!,
+  10,
+);
 
 type ContextValue = {
   name: string;
@@ -91,23 +97,8 @@ export function StableVersion(): ReactNode {
   return <span>{currentVersion}</span>;
 }
 
-// TODO temporary: assumes main is already on v3 (not the case yet)
-function useNextMajorVersionNumber(): number {
-  return 3; // TODO later read from main@package.json or something...
-}
-function useStableMajorVersionNumber(): number {
-  // -1 because website is published from main, which is the next version
-  return useNextMajorVersionNumber() - 1;
-}
-
-export function NextMajorVersion(): ReactNode {
-  const majorVersionNumber = useNextMajorVersionNumber();
-  return <span>{majorVersionNumber}</span>;
-}
-
 export function StableMajorVersion(): ReactNode {
-  const majorVersionNumber = useStableMajorVersionNumber();
+  return <span>{CurrentMajorVersionNumber}</span>;
-  return <span>{majorVersionNumber}</span>;
 }
 
 function GitBranchLink({branch}: {branch: string}): ReactNode {
@@ -119,12 +110,11 @@ function GitBranchLink({branch}: {branch: string}): ReactNode {
 }
 
 export function StableMajorBranchLink(): ReactNode {
-  const majorVersionNumber = useStableMajorVersionNumber();
+  // Can't be a link until the branch actually exists...
-  const branch = `docusaurus-v${majorVersionNumber}`;
+  return <code>{`docusaurus-v${CurrentMajorVersionNumber}`}</code>;
-  return <GitBranchLink branch={branch} />;
 }
 
-export function NextMajorBranchLink(): ReactNode {
+export function MainBranchLink(): ReactNode {
   return <GitBranchLink branch="main" />;
 }