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
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
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
,beta
orrc
pre-release - with the
@next
npm 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.