Cela fait plusieurs années que j’utilise git, principalement avec un outil graphique et parfois en ligne de commande.
Récemment, je suis tombé sur les règles de commit de AngularJS. Je vais vous expliquer comment écrire des messages de commit qui ont du sens et surtout pourquoi c’est important.
Pourquoi AngularJs comme exemple ?
Il y a quelques semaines, j’avais vu une vidéo qui parlait des règles de commit du projet AngularJS. Le sujet m’a beaucoup intéressé.
AugularJS est aujourd’hui un gros projet open source. Il a grandit vite et est géré par des grands du web comme Google (dont normalement, je me dis qu’ils doivent savoir coder).
J’ai donc analysé de plus prêt leur document qui explique les règles de commit.
En lisant la spéc, on se rend compte que c’est plutôt intéressant (même si c’est un peu long et très détaillé).
Pourquoi mettre en place des règles de commit ?
Dans ma carrière, j’ai rarement vu des règles de commit.
La conséquence, c’est que certains développeurs utilisaient des messages plus ou moins clairs et d’autres même « – » (si, si, j’ai vraiment vu ça).
Cela fait un moment que j’y pense et en étant tombé sur AngularJS, je me suis dit qu’il était temps de s’y pencher.
La mise en place de règles de commit va apporter plusieurs choses à votre projet :
- Premièrement : un message homogène dans les commits (et pas un contenu qui dépend de la personne et de sa motivation)
- Ensuite : la capacité d’être analysé ou extrait plus facilement car le message va suivre une certaine « grammaire »
- Enfin : cela permet aussi d’aider les nouveaux sur le projet pour les guider et leur expliquer quelles tournures il faut utiliser
La structure du message de commit
Selon AngularJS, le message doit avoir cette forme :
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>
Type décrit ce que fait votre commit. Voici les valeurs possibles :
- feat: une nouvelle fonctionnalité
- fix: une correction de bug
- docs: un changement uniquement dans la documentation
- style: un changement qui n’affecte pas le sens du code (espace, reformattage, alignements dans le code…)
- refactor: un changement qui n’est ni une correction de bug ni une évolution
- perf: un changement qui améliore la performance
- test: un ajout de tests manquants
- chore: un changement sur le process de build ou des outils complémentaires
Scope décrit le périmètre de votre modification. Les valeurs possibles sont les noms de vos composants par exemple.
Subject contient une description succincte de votre modification. Les verbes doivent être à l’impératif. Pas de majuscule au début et pas de point à la fin.
Body doit décrire la motivation des changements par rapport au commit précédent. Idem : verbes à l’impératif.
Footer est optionnel. Il décrit les bugs corrigés et référence donc le numéro de bug. Il peut être utilisé aussi pour décrire les changements qui cassent des choses (rétrocompatibilité par exemple).
Grâce à ce système de règles, le projet AngularJS est capable de générer un fichier changelog avec une structure cohérente (voir le CHANGELOG de AngularJS).
Plan d’action
Comme d’habitude, je vous propose un plan d’action pour démarrer et mettre en place des règles de commits. Vous aurez compris de c’est important pour assurer de la cohérence.
- Pour démarrer : je vous propose d’utiliser ces règles en listant les types et les scopes que vous pourriez avoir dans votre projet (la liste pourra évoluer dans le futur)
- Essayez de respecter ce formalisme pendant quelques jours lors de vos commits
- Après une semaine, générez un fichier CHANGELOG (par exemple avec : git log –oneline –decorate –color)
- Faites le point : est-ce que c’est difficile ? est-ce que ça apporte quelque chose ?
Que pensez-vous de ce système de règles ? Est-ce utile ?