docs: release process, versioning, breaking changes, public API surface (#7706)

Co-authored-by: Paul O’Shannessy <paul@oshannessy.com>
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

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,

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.
 

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 <StableMajorVersion/>**: the **stable** version, on the <StableMajorBranchLink/> branch
+- **Docusaurus <NextMajorVersion/>**: the **next** version, on the <NextMajorBranchLink/> branch
+
+:::note
+
+The <StableMajorBranchLink/> branch is created just before releasing the first v<StableMajorVersion/> release candidate.
+
+:::
+
+### Stable version {#stable-version}
+
+The stable version (v<StableMajorVersion/>, on <StableMajorBranchLink/>) is recommended for most Docusaurus users.
+
+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.
+
+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.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.
+
+:::

website/src/components/Versions.tsx

@@ -92,6 +92,43 @@ export function StableVersion(): JSX.Element {
   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(): JSX.Element {
+  const majorVersionNumber = useNextMajorVersionNumber();
+  return <span>{majorVersionNumber}</span>;
+}
+
+export function StableMajorVersion(): JSX.Element {
+  const majorVersionNumber = useStableMajorVersionNumber();
+  return <span>{majorVersionNumber}</span>;
+}
+
+function GitBranchLink({branch}: {branch: string}): JSX.Element {
+  return (
+    <a href={`https://github.com/facebook/docusaurus/tree/${branch}`}>
+      <code>{branch}</code>
+    </a>
+  );
+}
+
+export function StableMajorBranchLink(): JSX.Element {
+  const majorVersionNumber = useStableMajorVersionNumber();
+  const branch = `docusaurus-v${majorVersionNumber}`;
+  return <GitBranchLink branch={branch} />;
+}
+
+export function NextMajorBranchLink(): JSX.Element {
+  return <GitBranchLink branch="main" />;
+}
+
 export function InsertIfCanaryVersionUnknown({
   children,
 }: {