Comment bien écrire vos messages de commit ?
Découvrez les bonnes pratiques et une convention de nommage pour vos messages de commit avec Git !
Article publié le 15/04/2024, dernière mise à jour le 15/04/2024
La force de Git est bien évidemment de stocker et versionner toutes les modifications d’un code source au fil du temps, afin de garder un historique et de pouvoir revenir à une version antérieure s’il y a besoin.
Mais on ne peut parcourir un historique de manière efficace, que si l’on sait ce que l’on parcoure…
En effet, les messages des commits (versions) sont une facette très importante de la gestion d’un projet de développement !
Chaque commit peut contenir un grand nombre d'infos importantes, et il est nécessaire de trouver une structure de message qui :
- soit facilement compréhensible
- pas trop difficile à écrire
- qui hiérarchise bien les informations
Heureusement, il existe une convention qui coche toutes les bonnes cases : les
conventional commits
Conventional commits
Dans l’idéal, un message de commit doit contenir toutes les informations nécessaires à la bonne compréhension d’un humain, et donc :
- Le type de changement (nouvelle fonctionnalité par exemple)
- La portée du changement (la partie du code modifiée, comme un module)
- La description de ce changement
- Le numéro du ticket, ou “issue” corrigé (optionnel)
Et voici le format conseillé par cette convention :
<type>[optional scope]: <description>
[optional body]
[optional footer]
Ce qui donne un exemple de commit comme celui-ci :
fix(user): authenticate user with email instead of username
Issue #132
La spécification contient 15 règles précises à suivre, comme les types de commit : feat
, fix
, refactor
, build
, chore
, ci
, docs
, style
, test
,…
Vous pourrez retrouver toutes les informations, et les valeurs possibles, liées à cette convention sur le site dédié : https://www.conventionalcommits.org/en/
En bonus : cette convention permet de parser les messages de commit assez facilement pour une machine, et donc de générer des changelogs par exemple !
Une variation personnalisée
À titre personnel, j’ai longtemps utilisé une variante (avant de connaitre la convention du dessus) assez proche, légèrement plus concise, comme ceci :
[TYPE] scope (#issue) - message
Ce qui donne des messages de commit ressemblant à ceci :
- [REFACTOR] User (#5) - Merging User and Account models
- [FIX] Notifications (#18) - Emails were not sending due to wrong smtp credentials
- [FEATURE] Post (#65) - Images can be added to posts using the editor
Il est quand même très conseillé d’utilisé les
conventional commits
mais libre à vous d’opter pour celle-ci
Car une même une convention non-standard vaut mieux que pas de convention du tout (et ne parlons pas des commits sans message…)
Aucun commentaire pour l'instant