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
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
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
Versões
The Docusaurus team is usually working on 2 major versions at the same time:
- Docusaurus 2: the stable version, on the
docusaurus-v2branch - Docusaurus 3: the next version, on the
mainbranch
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.
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,betaorrcpre-release - with the
@nextnpm dist tag for the latest pre-release - with a canary release for the very latest features
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.
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.
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
- Opções de predefinição
- Opções do plugin
- Plugin lifecycle APIs
- Theme config
- Core plugins route component props
@docusaurus/typesTypeScript 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_orunstable_ - 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:
- Theme class names
- Infima class names and CSS variables
- React components that are safe to swizzle
- The theme user experience
- Suporte ao navegador
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.