mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-02 08:19:07 +02:00
docs: adjust the Docusaurus release process documentation to our new simpler process (#11181)
Co-authored-by: slorber <749374+slorber@users.noreply.github.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
9f6360ba82
commit
484ffad4f2
5 changed files with 25 additions and 74 deletions
|
|
@ -183,7 +183,6 @@ navigations
|
|||
navlink
|
||||
netrc
|
||||
newtab
|
||||
ngryman
|
||||
Nisarag
|
||||
noflash
|
||||
noicon
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <StableMajorVersion/>**: the **stable** version, on the <StableMajorBranchLink/> branch
|
||||
- **Docusaurus <NextMajorVersion/>**: the **next** version, on the <NextMajorBranchLink/> branch
|
||||
- **Docusaurus {CurrentMajorVersionNumber}**: the **stable** version, on the <MainBranchLink/> 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.
|
||||
|
||||
:::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 <StableMajorBranchLink/> 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<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.
|
||||
|
|
|
|||
|
|
@ -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>{majorVersionNumber}</span>;
|
||||
return <span>{CurrentMajorVersionNumber}</span>;
|
||||
}
|
||||
|
||||
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 <GitBranchLink branch={branch} />;
|
||||
// Can't be a link until the branch actually exists...
|
||||
return <code>{`docusaurus-v${CurrentMajorVersionNumber}`}</code>;
|
||||
}
|
||||
|
||||
export function NextMajorBranchLink(): ReactNode {
|
||||
export function MainBranchLink(): ReactNode {
|
||||
return <GitBranchLink branch="main" />;
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue