Comment bien écrire vos messages de commit ?

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…)