diff --git a/project-words.txt b/project-words.txt index d048138934..18363f6eec 100644 --- a/project-words.txt +++ b/project-words.txt @@ -183,7 +183,6 @@ navigations navlink netrc newtab -ngryman Nisarag noflash noicon diff --git a/website/blog/releases/3.0/index.mdx b/website/blog/releases/3.0/index.mdx index 66b7043121..87496cd352 100644 --- a/website/blog/releases/3.0/index.mdx +++ b/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. ::: diff --git a/website/community/4-canary.mdx b/website/community/4-canary.mdx index 698dd1f8ac..cf337558cb 100644 --- a/website/community/4-canary.mdx +++ b/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. diff --git a/website/community/5-release-process.mdx b/website/community/5-release-process.mdx index fae6a1a046..5377f3dd65 100644 --- a/website/community/5-release-process.mdx +++ b/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, - NextMajorVersion, + CurrentMajorVersionNumber, 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 **: the **stable** version, on the branch -- **Docusaurus **: the **next** version, on the branch +- **Docusaurus {CurrentMajorVersionNumber}**: the **stable** version, on the branch. -:::note +:::note How we will ship the next version -The branch is created just before releasing the first v release candidate. +Once we are ready ship **Docusaurus {CurrentMajorVersionNumber + 1}**, we will: + +- create a branch +- merge breaking changes on the branch +- release that new version directly from the branch ::: -### Stable version {#stable-version} +:::warning Security fixes policy -The stable version (v, on ) 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 to with `git cherry-pick` to make them available to those not ready for the next version. - -:::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. +In practice, we will backport security fixes to the branch. 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, on ) is the version the Docusaurus team is currently working on. - -The 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. diff --git a/website/src/components/Versions.tsx b/website/src/components/Versions.tsx index 9ce7547273..78de5d43a8 100644 --- a/website/src/components/Versions.tsx +++ b/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 {currentVersion}; } -// 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 {majorVersionNumber}; -} - export function StableMajorVersion(): ReactNode { - const majorVersionNumber = useStableMajorVersionNumber(); - return {majorVersionNumber}; + return {CurrentMajorVersionNumber}; } function GitBranchLink({branch}: {branch: string}): ReactNode { @@ -119,12 +110,11 @@ function GitBranchLink({branch}: {branch: string}): ReactNode { } export function StableMajorBranchLink(): ReactNode { - const majorVersionNumber = useStableMajorVersionNumber(); - const branch = `docusaurus-v${majorVersionNumber}`; - return ; + // Can't be a link until the branch actually exists... + return {`docusaurus-v${CurrentMajorVersionNumber}`}; } -export function NextMajorBranchLink(): ReactNode { +export function MainBranchLink(): ReactNode { return ; }