Skip to main content

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​

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
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, but we still group breaking changes together and avoid releasing major versions too often.

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 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
tip

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 is usually working on 2 major versions at the same time:

  • Docusaurus 2: the stable version, on the docusaurus-v2 branch
  • Docusaurus 3: the next version, on the main branch
note

The docusaurus-v2 branch is created just before releasing the first v2 release candidate.

Stable version​

The stable version (v2, on docusaurus-v2) is recommended for most Docusaurus users.

We regularly backport retro-compatible features, bug and security fixes from main to docusaurus-v2 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​

The next version (v3, on main) is the version the Docusaurus team is currently working on.

The main 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 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​

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​

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

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:

tip

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
note

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.