Aller au contenu principal

Processus de version

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

info

Ce sujet est particulièrement important pour les sites hautement personnalisés qui peuvent avoir des difficultés pour la mise à niveau.

Versionnage sémantique​

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

Le respect du versionnage sémantique est important pour plusieurs raisons :

  • It guarantees simple minor version upgrades, as long as you only use the public API
  • Il respecte les conventions de l'écosystème front-end
  • Une nouvelle version majeure est l'occasion de documenter minutieusement les changements de rupture
  • Une nouvelle version majeure ou mineure est l'occasion de communiquer les nouvelles fonctionnalités par le biais d'un article du blog

Versions majeures​

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.
  • une entrée du changelog exhaustive
astuce

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

Versions mineures​

The minor version number is incremented on every significant retro-compatible change.

Whenever a new minor version is released, we publish:

  • un article du blog contenant une liste des principales fonctionnalités et des principaux correctifs de bogues
  • une entrée du changelog exhaustive
astuce

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

About End-of-Life Node.js versions

We may drop support for End-of-Life Node.js versions in minor Docusaurus versions. Check the Node.js support policy section for more details.

Versions correctives​

The patch version number is incremented on bugfixes releases.

Whenever a new patch version is released, we publish:

  • une entrée du changelog exhaustive

Node.js support policy​

Each major version of Docusaurus supports a minimum Node.js version. This retro-compatibility will be preserved all along that release line. This runtime backward compatibility will be preserved throughout all the minor versions of the release line, except for End-of-Life Node.js versions.

Support for End-of-Life versions

On minor releases, we reserve the right to drop support for Node.js versions that reached End-of-Life (Node.js release process and schedule. We do not consider it a Docusaurus breaking change. We highly recommend using a maintained Node.js version. Beware that End-of-Life Node.js versions do not receive security updates anymore.

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.

Surface de l'API publique​

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.

astuce

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:

  • Configuration de Docusaurus
  • API client Docusaurus
  • CLI de Docusaurus
  • Options du preset
  • Options du plugin
  • API du cycle de vie des plugins
  • Configuration du thème
  • Props du composant de route des plugins de base
  • @docusaurus/types TypeScript types
    • Nous conservons toujours la liberté de rendre les types plus stricts (ce qui peut casser la vérification de type).

❌ Our public API excludes:

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

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:

  • Vous pouvez utiliser un CSS personnalisé
  • 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:

astuce

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:

  • La structure DOM
  • 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
  • L'apparence visuelle exacte du thème
remarque

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.