diff --git a/packages/docusaurus-plugin-content-docs/src/server-export.ts b/packages/docusaurus-plugin-content-docs/src/server-export.ts index 7cde21eb40..0212758b78 100644 --- a/packages/docusaurus-plugin-content-docs/src/server-export.ts +++ b/packages/docusaurus-plugin-content-docs/src/server-export.ts @@ -6,6 +6,10 @@ */ // APIs available to Node.js +// Those are undocumented but used by some third-party plugins +// For this reason it's preferable to avoid doing breaking changes +// See also https://github.com/facebook/docusaurus/pull/6477 + export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, diff --git a/website/community/4-canary.md b/website/community/4-canary.md index 07e092907f..ae866c4d33 100644 --- a/website/community/4-canary.md +++ b/website/community/4-canary.md @@ -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. +It permits you to **test new unreleased features** as soon as the pull requests are merged on the [next version](./5-release-process.md#next-version) of Docusaurus. 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.md b/website/community/5-release-process.md new file mode 100644 index 0000000000..6afe0421d2 --- /dev/null +++ b/website/community/5-release-process.md @@ -0,0 +1,206 @@ +# Release process + +Let's see how Docusaurus handles **versioning, releases and breaking changes**. + +:::info + +This topic is particularly important for highly customized sites that may have difficulties to upgrade. + +::: + +## Semantic versioning {#semantic-versioning} + +Docusaurus versioning is based on the `major.minor.patch` scheme and respects [Semantic Versioning](https://semver.org/). + +Respecting Semantic Versioning is important for multiple reasons: + +- It **guarantees simple minor version upgrades**, as long as you only use the [public API](##public-api-surface) +- It follows front-end ecosystem conventions +- 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**. + +Whenever a new major version is released, we publish: + +- a blog post with feature highlights, major bug fixes, **breaking changes, and upgrade instructions**. +- an exhaustive changelog entry + +:::tip + +Read our [public API surface](##public-api-surface) section to clearly understand what we consider as a breaking change. + +::: + +### Minor versions {#minor-versions} + +The `minor` version number is incremented on every significant retro-compatible change. + +Whenever a new minor version is released, we publish: + +- a blog post with a list of feature highlights and major bug fixes +- an exhaustive changelog entry + +:::tip + +If you only use our [public API surface](##public-api-surface), you should be able to upgrade in no time! + +::: + +### Patch versions {#patch-versions} + +The `patch` version number is incremented on bugfixes releases. + +Whenever a new patch version is released, we publish: + +- an exhaustive changelog entry + +## Versions {#versions} + +```mdx-code-block +import { + StableMajorVersion, + NextMajorVersion, + StableMajorBranchLink, + NextMajorBranchLink, +} from "@site/src/components/Versions"; +``` + +The Docusaurus team is usually working on 2 major versions at the same time: + +- **Docusaurus **: the **stable** version, on the branch +- **Docusaurus **: the **next** version, on the branch + +:::note + +The branch is created just before releasing the first v release candidate. + +::: + +### Stable version {#stable-version} + +The stable version (v, on ) is recommended for most Docusaurus users. + +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. + +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.md) 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. + +::: + +:::caution + +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. + +:::tip + +Docusaurus guarantees public API retro-compatibility across `minor` versions. Unless you use internal APIs, `minor` version upgrades should be easy. + +::: + +We will outline what accounts as the public API surface. + +### Core public API {#core-public-api} + +✅ Our public API includes: + +- Docusaurus config +- Docusaurus client APIs +- Docusaurus CLI +- Preset options +- Plugin options +- Plugin lifecycle APIs +- Theme config +- Core plugins route component props +- `@docusaurus/types` TypeScript types + - We still retain the freedom to make types stricter (which may break type-checking). + +:::tip + +For non-theme APIs, any documented API is considered public (and will be stable); any undocumented API is considered internal. + +::: + +An API being "stable" means if you increment the patch or minor version of your Docusaurus installation without any other change, running `docusaurus start` or `docusaurus build` should not throw an error. + +### Theming public API {#theming-public-api} + +Docusaurus has a very flexible theming system: + +- You can use custom CSS +- You can [swizzle](/docs/swizzling) any React theme component + +This system also implicitly creates a very large API surface. To be able to move fast and improve Docusaurus, we can't guarantee retro-compatibility. + +✅ Our public theming API includes: + +- [Theme class names](/docs/styling-layout#theme-class-names) +- [Infima](/docs/styling-layout#styling-your-site-with-infima) class names and CSS variables +- React components that are [safe to swizzle](/docs/swizzling#what-is-safe-to-swizzle) +- The theme user experience +- Browser support + +:::tip + +You may not be able to achieve your site customization through this public API. + +In this case, please [report your customization use case](https://github.com/facebook/docusaurus/discussions/5468) and we will figure out how to expand our public API. + +::: + +❌ Our public theming API **excludes**: + +- The DOM structure +- CSS module class names with a hash suffix (usually targeted with `[class*='myClassName']` selectors) +- React components that are [unsafe or forbidden to swizzle](/docs/swizzling#what-is-safe-to-swizzle) +- React components that import from `@docusaurus/theme-common/internal` +- The exact visual appearance of the theme + +:::note + +When [swizzling](/docs/swizzling) safe components, you might encounter components that import undocumented APIs from `@docusaurus/theme-common` (without the `/internal` subpath). + +We still maintain retro-compatibility on those APIs (hence they are marked as "safe"), but we don't encourage a direct usage. + +::: diff --git a/website/src/components/Versions.tsx b/website/src/components/Versions.tsx index 9542c88a83..1a32226cf3 100644 --- a/website/src/components/Versions.tsx +++ b/website/src/components/Versions.tsx @@ -92,6 +92,43 @@ export function StableVersion(): JSX.Element { 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(): JSX.Element { + const majorVersionNumber = useNextMajorVersionNumber(); + return {majorVersionNumber}; +} + +export function StableMajorVersion(): JSX.Element { + const majorVersionNumber = useStableMajorVersionNumber(); + return {majorVersionNumber}; +} + +function GitBranchLink({branch}: {branch: string}): JSX.Element { + return ( + + {branch} + + ); +} + +export function StableMajorBranchLink(): JSX.Element { + const majorVersionNumber = useStableMajorVersionNumber(); + const branch = `docusaurus-v${majorVersionNumber}`; + return ; +} + +export function NextMajorBranchLink(): JSX.Element { + return ; +} + export function InsertIfCanaryVersionUnknown({ children, }: {