Aller au contenu principal

Processus de version

Voyons comment Docusaurus gère le versionnage, les publications et les changements de rupture.

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​

Le versionnage de Docusaurus est basé sur le schéma major.minor.patch et respecte le Versionnage sémantique.

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

  • Il garantit de simples mises à jour de versions mineures, tant que vous n'utilisez que l'API publique
  • 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
remarque

La sortie de Docusaurus 2.0 a pris beaucoup de temps. Dorénavant, Docusaurus publiera plus régulièrement de nouvelles versions majeures. En pratique, vous pouvez vous attendre à une nouvelle version majeure tous les 2-4 mois.

Les numéros de version majeure ne sont pas sacrés, mais nous regroupons tout de même les changements de rupture et évitons de sortir des versions majeures trop souvent.

Versions majeures​

Le numéro de version majeur est incrémenté sur chaque changement de rupture.

Chaque fois qu'une nouvelle version majeure est publiée, nous publions :

  • un article du blog contenant les principales fonctionnalités, les corrections de bogues majeurs, les changements de rupture et les instructions de mise à niveau.
  • une entrée du changelog exhaustive
astuce

Lisez notre section Surface de l'API publique pour comprendre clairement ce que nous considérons comme un changement de rupture.

Versions mineures​

Le numéro de version minor est incrémenté à chaque changement rétro-compatible important.

Chaque fois qu'une nouvelle version mineure est publiée, nous publions :

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

Si vous n'utilisez que notre Surface de l'API publique, vous devriez être en mesure de le mettre à jour en un rien de temps !

Versions correctives​

Le numéro de version patch est incrémenté sur les versions de corrections de bugs.

Chaque fois qu'une nouvelle version corrective est publiée, nous publions :

  • une entrée du changelog exhaustive

Versions​

L'équipe Docusaurus travaille généralement sur 2 versions majeures en même temps :

  • Docusaurus 2 : la version stable sur la branche docusaurus-v2
  • Docusaurus 3 : la version next sur la branche main
remarque

La branche docusaurus-v2 est créée juste avant la publication de la première release candidate de la v2.

Version stable​

La version stable (v2, sur docusaurus-v2) est recommandée pour la plupart des utilisateurs de Docusaurus.

Nous reportons régulièrement les fonctionnalités rétro-compatibles, les corrections de bogues et de sécurité de main sur docusaurus-v2 avec git cherry-pick pour les rendre disponibles à ceux qui ne sont pas prêts pour la prochaine version.

info

Après la sortie d'une nouvelle version stable, l'ancienne version stable continuera de recevoir le support uniquement pour les problèmes de sécurité majeurs pendant 3 mois. Sinon, toutes les fonctionnalités seront bloquées et les bogues non critiques ne seront pas corrigés.

Il est recommandé de mettre à jour la nouvelle version stable dans ce laps de temps.

Version suivante (next)​

La version next (v3, sur main) est la version sur laquelle l'équipe Docusaurus est en train de travailler.

La branche main est la branche cible par défaut pour toutes les pull requests, comprenant celle de l'équipe principale et les contributions externes.

Cette version est recommandée pour les adopteurs précoces qui veulent utiliser les dernières fonctionnalités du Docusaurus dès que possible. C'est aussi un bon moyen de nous aider en signalant des bogues et en donnant quelques retours.

Il y a 3 façons d'utiliser la prochaine version :

  • avec une pré-version alpha, beta ou rc
  • avec la balise @next pour npm pour la dernière préversion
  • avec une version canary pour les toutes dernières fonctionnalités
astuce

La version next passe tous nos tests automatisés et est utilisée par le site Docusaurus lui-même. Elle est relativement sûre : n'ayez pas peur de l'essayer.

attention

Les changements de rupture peuvent être effectués sur la prochaine version : des instructions détaillées de mise à niveau sont disponibles dans le changelog et les pull requests.

Lors des phases beta et rc (release candidate), nous évitons d'introduire des changements de rupture majeurs.

Surface de l'API publique​

Docusaurus s'engage à respecter le versionnage sémantique. Cela signifie que chaque fois que des changements se produisent dans les API publiques de Docusaurus et brisent la rétrocompatibilité, nous incrémenterons le numéro de version major.

astuce

Docusaurus garantit la rétro-compatibilité de l'API publique entre les versions minor. Sauf si vous utilisez des API internes, les mises à jour de version minor devraient être faciles.

Nous allons décrire ce que sont les comptes en tant que surface de l'API publique.

API publique principale​

✅ Notre API publique comprend :

  • 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
  • les types TypeScript @docusaurus/types
    • Nous conservons toujours la liberté de rendre les types plus stricts (ce qui peut casser la vérification de type).

❌ Notre API publique exclut :

  • Configuration Docusaurus future
  • Toutes les fonctionnalités préfixées par experimental_ ou unstable_
  • Toutes les fonctionnalités préfixées par v<MajorVersion>_ (v6_ v7_, etc.)
astuce

Pour les API non-thèmes, toute API documentée est considérée comme publique (et sera stable) ; toute API non documentée est considérée comme interne.

Une API considérée comme « stable » signifie que si vous incrémentez le patch ou la version mineure de votre installation Docusaurus sans autre changement, l'exécution de docusaurus start ou docusaurus build ne devrait pas lancer une erreur.

API publique de thème​

Docusaurus a un système de thème très flexible :

  • Vous pouvez utiliser un CSS personnalisé
  • Vous pouvez faire un swizzle sur n'importe quel composant de thème React

Ce système crée également implicitement une très grande surface de l'API. Pour pouvoir avancer rapidement et améliorer Docusaurus, nous ne pouvons pas garantir la rétrocompatibilité.

✅ Notre API de thème publique comprend :

astuce

Il se peut que vous ne puissiez pas réaliser la personnalisation de votre site via cette API publique.

Dans ce cas, veuillez signaler votre cas d'utilisation personnalisé et nous allons déterminer comment étendre notre API publique.

❌ Notre API de thème public exclut :

  • La structure DOM
  • Les noms de classe des modules CSS avec un suffixe de hachage (généralement visés par les sélecteurs [class*='myClassName'])
  • Les composants React qui sont dangereux ou interdits pour le swizzle
  • Les composants React qui importent depuis @docusaurus/theme-common/internal
  • L'apparence visuelle exacte du thème
remarque

Lors du swizzling sur des composants sûrs, vous pouvez rencontrer des composants qui importent des API non documentées depuis @docusaurus/theme-common (sans le sous-chemin /internal).

Nous maintenons toujours la rétro-compatibilité sur ces APIs (c'est pourquoi elles sont marquées comme « sûrs »), mais nous n'encourageons pas une utilisation directe.