メインコンテンツまでスキップ

Release process

Let's see how Docusaurus handles versioning, releases and breaking changes.

備考

This topic is particularly important for highly customized sites that may have difficulties to upgrade.

Semantic versioning​

Docusaurus versioning is based on the major.minor.patch scheme and respects Semantic Versioning.

Respecting Semantic Versioning is important for multiple reasons:

  • It guarantees simple minor version upgrades, as long as you only use the public API
  • 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

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
ヒント

Read our public API surface section to clearly understand what we consider as a breaking change.

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
ヒント

If you only use our public API surface, you should be able to upgrade in no time!

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​

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 3: the stable version, on the main branch.
How we will ship the next version

Once we are ready ship Docusaurus 4, we will:

  • create a docusaurus-v3 branch
  • merge breaking changes on the main branch
  • release that new version directly from the main branch
Security fixes policy

After a new stable version has been released, the former stable version will continue to receive support for major security issues for 3 months.

In practice, we will backport security fixes to the docusaurus-v3 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.

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.

ヒント

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​

✅ 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).

❌ Our public API excludes:

  • Docusaurus config future
  • All features prefixed by experimental_ or unstable_
  • All features prefixed by v<MajorVersion>_ (v6_ v7_, etc.)
ヒント

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​

Docusaurus has a very flexible theming system:

  • You can use custom CSS
  • You can swizzle 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:

ヒント

You may not be able to achieve your site customization through this public API.

In this case, please report your customization use case 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
  • React components that import from @docusaurus/theme-common/internal
  • The exact visual appearance of the theme
注記

When 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.