Commit conventionnel
Lorsqu’on arrive à certain stade de qualité dans nos projets Git, intervient la question de normer les messages de commit ou, a minima, de définir une convention de rédaction. Pendant de nombreuses années, chacun y allait à sa sauce. Puis, comme pour les versions logicielles, certaines initiatives ont vu le jour, des similitudes ont été trouvées à travers les différentes manières de faire au sein de différentes organisations, et une convention a emergé.
Pourquoi utiliser une convention
Les avantages sont multiples :
- Clarifie la communication sur les évolutions du projet ;
- Facilite la contribution au projet ;
- Ouvre la voie à l’automatisation : changelog, montée de version logicielle.
Bonjour « Conventional Commit »
Cette convention est le résultat d’un travail collaboratif et ouvert. Elle trouve ses origines auprès des équipes travaillant sur AngularJS. Nous leur devons l’essentiel du format actuel.
La documentation complète est disponible sur le site conventionalcommits.org.
Format
La convention définit un format de message type :
<type>[contexte optionnel]: <description>
[corps optionnel]
[notes/pied de message optionnels]
Il satisfait les critères suivants :
- favorise la catégorisation “classique” (le type) ;
- permet de sous-catégoriser selon un contexte, complémentaire au type, mais apportant plus de souplesse/liberté ;
- décrit de manière concise (à l’impératif) en premier lieu le contenu, afin de favoriser la lecture du log “oneline” ;
- permet de décrire plus précisemment le contenu, s’il y a lieu ;
- permet de fournir des informations clés à la gestion de projet (numéro de ticket, note de version…).
Il est ainsi prévu pour être adapté à nos besoins tout en respectant les 2 contraintes fortes qui sont :
- le classement par thème ;
- la facilité de lecture de la première ligne du message (et donc de l’historique / du log).
Les “types” disponibles
La liste des types disponibles est volontairement limitée mais couvre toutes les situations :
- feat : ajout/mise à jour de fonctionnalité ;
- fix : correction de bug ;
- docs : ajout/mise à jour de documentation ;
- style : modification de style et de mise en forme du code (espacements, virgules, etc.) ;
- refactor : modification des sources n’étant ni un correctif, ni un ajout de fonctionnalité ;
- perf : amélioration de la performance ;
- test : ajout ou correction de test ;
- build : modification affectant le “build” ou les dépendances externes (exemples de contextes : webpack, broccoli, npm) ;
- chore : autres mises à jour ne modifiant ni les sources, ni les tests ;
- ci : modification de la configuration ou des scripts liés à la CI (Travis, Circle, BrowserStack, SauceLabs, etc.) ;
- revert : annuler (revert) un commit précédent.
Cette liste a été conçue pour répondre aux critères du Semantic Versioning et ouvre dès lors à un potentiel d’automatisation via des outils comme Semantic Release qui permet l’automatisation des publications de versions et la génération automatique des notes de version (ou changelog).
Types et Semantic Versioning
Seuls certains types et mots clés ont un rapport avec le semantic versioning :
- feat : le commit induit une montée de version mineure ;
- fix : induit une montée de version de type patch.
La montée de version majeure peut être réalisée selon 2 procédés/syntaxes ::
- En utilisant le point d’exclamation en suffixe de n’importe quel type (exemple :
chore!: drop support for Node 6
) ; - En ajoutant en note de pied les mots clés
BREAKING CHANGE
.
Existe-t-il des alternatives ?
Oui ! Elles sont généralement associées à des contextes ou technologies spécifiques, à l’image des scopes lerna.
Certaines visent à adopter d’autres sémantiques pour les types, comme gitmoji qui recourt aux emojis pour permettre une interprétation plus visuelle de notre historique.
Peut-on garantir le respect d’une convention ?
Il est difficile de garantir à 100% le respect sans se dotter d’outils complémentaires. Les hooks Git peuvent alors se montrer êtres alliés précieux en agissant à différents niveaux :
- au moment de la rédaction du commit ;
- en vérification du commit ;
- sur le serveur Git, en vérification complémentaire.
Si tu veux creuser plus ce sujet et voir une méthode d’automatisation simple et efficace, nous avions un article à ce sujet.
Tu peux aussi regarder le programme de notre formation "Comprendre Git" ou nous poser tes questions sur notre forum discord.