Processus de version
Voyons comment Docusaurus gère le versionnage, les publications et les changements de rupture.
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
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
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
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
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.
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
ourc
- avec la balise
@next
pour npm pour la dernière préversion - avec une version canary pour les toutes dernières fonctionnalités
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.
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
.
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_
ouunstable_
- Toutes les fonctionnalités préfixées par
v<MajorVersion>_
(v6_
v7_
, etc.)
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 :
- Les noms de la classe du thème
- Les noms de classe et les variables CSS de Infima
- Les composants React qui sont sûrs pour le swizzle
- L'expérience utilisateur du thème
- Navigateurs pris en charge
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
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.