ADR-002 : Stratégie de versionning de la documentation
Statut
Acceptée
Contexte
Balyze comprend une documentation technique en constante évolution.
Dès les premières étapes du projet, il a été nécessaire de décider comment cette documentation devait être versionnée par rapport au produit lui-même.
Plusieurs approches étaient possibles :
- un couplage strict entre les versions du code et celles de la documentation
- un versionning indépendant de la documentation
- l’hébergement simultané de plusieurs versions de la documentation
Au stade ALPHA, la priorité est donnée à la simplicité et à la maintenabilité plutôt qu’à l’exhaustivité.
Décision
La documentation technique est versionnée indépendamment du code applicatif.
La stratégie suivante est adoptée :
- la branche
mainreprésente l’état validé courant de la documentation - la documentation en ligne reflète toujours l’état le plus récent de
main - les jalons documentaires majeurs sont matérialisés par des tags Git
- les pages indiquent explicitement la phase produit applicable (ex. ALPHA)
Aucun hébergement multi-version de la documentation n’est mis en place à ce stade.
Justification
Cette approche :
- évite une complexité prématurée
- permet à la documentation d’évoluer en continu
- offre une traçabilité claire via les tags Git
- maintient un workflow léger et prévisible
La documentation fait autorité pour l’état actuel validé du produit.
Conséquences
Positives
- workflow simple et compréhensible
- aucune surcharge liée aux branches multiples
- onboarding facilité pour les contributeurs
- absence de dépendance à un outil de versionning spécifique
Compromis
- les anciennes versions ne sont pas directement navigables en ligne
- l’accès à un état historique nécessite de consulter un tag Git
Ces compromis sont jugés acceptables au stade ALPHA.
Considérations futures
À mesure que le produit atteindra la BETA ou la v1 :
- un outil de documentation multi-version (ex.
mike) pourra être introduit - un alignement plus étroit entre versions produit et documentation pourra être envisagé
Toute évolution nécessitera une nouvelle décision architecturale.