Un modèle publié est une dépendance de production
Lorsqu’une application génère des factures, contrats ou rapports, le template fait partie du comportement livré au client. Le modifier en place revient à changer une dépendance de production sans version ni historique.
Le versioning répond à trois questions simples : qu’est-ce qui a changé, qui l’a validé et comment revenir à un état stable ?
Un cycle de vie minimal
Un cycle utile n’a pas besoin de dix statuts. Quatre suffisent souvent :
- Brouillon : la version peut évoluer et n’est pas utilisée en production.
- En revue : le changement est figé le temps de la vérification.
- Publiée : la version peut générer des documents réels.
- Archivée : elle reste consultable mais ne reçoit plus de nouveaux changements.
L’important est qu’une version publiée ne soit pas réécrite silencieusement.
Que faut-il versionner ?
Versionnez l’ensemble qui détermine le résultat : structure, styles, champs attendus, textes stables, assets référencés, données d’exemple et note de changement. Si la police ou le logo peut changer indépendamment, conservez aussi leur référence exacte.
Un numéro seul ne suffit pas. La version doit rester liée au document généré ou au job de génération afin de rendre un incident explicable plusieurs semaines plus tard.
Revue et changelog
Le changelog doit décrire l’impact, pas seulement l’action. « Déplacé le bloc » explique peu. « Évite que l’adresse client passe sur une deuxième page » donne au relecteur une raison vérifiable.
La revue devrait utiliser plusieurs payloads : cas nominal, données minimales et données extrêmes. Pour les documents réglementés, ajoutez la validation de la personne compétente ; l’outil ne remplace pas cette responsabilité.
Restaurer sans effacer l’histoire
Un rollback ne devrait pas supprimer la version défectueuse. Créez plutôt une nouvelle version à partir du dernier état stable et conservez un lien vers la source restaurée. Vous obtenez alors une chronologie complète : changement, incident, décision et restauration.
Cette stratégie évite aussi de modifier rétroactivement les preuves liées aux documents déjà produits.
Vers des environnements nommés
À mesure que le produit mûrit, des alias comme dev, staging et prod permettent de promouvoir une version sans modifier le code client. L’alias pointe vers une version immuable. La promotion change le pointeur, pas le template lui-même.
Ce mécanisme devient particulièrement utile quand plusieurs applications consomment le même modèle.
Checklist de gouvernance
- Une version publiée est immuable.
- Chaque génération garde l’identifiant de version.
- Le changelog décrit l’impact attendu.
- La revue utilise plusieurs jeux de données.
- La restauration crée un nouvel événement traçable.
- Les droits de publication sont limités.
- Les versions anciennes restent accessibles selon une politique définie.
Questions fréquentes
Faut-il appliquer SemVer aux templates ?
Pas obligatoirement. La notion majeure, mineure ou corrective devient utile quand le schéma de données est comparé automatiquement. Avant cela, un numéro séquentiel et un changelog rigoureux sont déjà précieux.
Peut-on supprimer une ancienne version ?
Évitez de supprimer une version utilisée par des documents réels. Archivez-la et appliquez une politique de conservation compatible avec vos obligations.