explain commit message
Au moment de créer un nouveau commit, git demande à l'utilisateur de décrire les changements effectués via le message de commit. La rédaction de ces messages peut sembler fastidieuse voire inutile, aussi bien aux novices qu'aux personnes plus expérimentés, mais est d'une importance capitale pour mener à bien un projet de développement informatique sur le long terme.
Ce document se découpe en plusieurs partie. La première partie est consacrée à expliquer l'origine des messages de commit et leurs liens avec les emails échangés entre les contributeurs au kernel Linux. La seconde partie découpe la structure d'un message de commit et explique quoi mettre à quel endroit. La troisième partie explique où et quand sont lus les messages de commit et explicite pourquoi il est important de prendre du temps à rédiger des bons messages de commit. Pour finir une quatrième partie plus succincte donne quelques pistes pour évaluer la qualité des commits et de l'historique git d'un projet et comment l'améliorer.
Git a été développé afin de rendre possible la collaboration à grande échelle sur le noyau Linux. Avant d'utiliser git, les développeurs du noyau collaboraient à l'aide de mailing-list, ils discutaient des changements à venir ou en cours via mail et s'échangeaient du code en pièce jointe.
Le développement d'une nouvelle fonctionnalité commençait par envoyer un email
à tout le monde qui avait souscrit à la mailing-list pour décrire les nouveaux
besoins. Si vous trouviez un bug dans le kernel, vous pouviez envoyer un mail à
cette mailing-list pour décrire le bug et demander à ce qu'il soit corrigé.
Quiconque intéressé pouvait alors "répondre à tous" sur cet email et ouvrir une
discussion autours de la fonctionnalité à développer ou du bug à corriger.
Après quelques jours, quelqu'un répondait à la suite d'email avec un patch,
c'est à dire une archive compressée (un .zip) qui contenait l'ensemble des
diff à appliquer aux fichiers sources du kernel. Les autres développeurs
répondaient avec cet email pour donner leur avis sur les changements dans le
but d'arriver à la meilleure solution. Une fois le patch approuvé par tout le
monde (enfin surtout par Linus), il pouvait être appliqué sur le kernel et
inclus dans les nouvelles versions.
Dans le lot, le développeur qui avait pris la peine de proposer un patch ne devait pas se contenter de répondre un email vide avec le code en pièce jointe. Il avait aussi la responsabilité de résumer les discussions préalable et d'apporter des possibles éclaircissement sur son code. L'idée générale étant de faire gagner du temps à tout le monde (et surtout à Linus) en rappelant le contexte, les besoins et en apportant des explications quant à l'implémentation si ce n'était pas trivial.
Comme git a été développé avec comme objectif d'être utilisé par les contributeurs du kernel Linux, cette idée d'accompagner chaque contribution par un message explicatif a été reprise et a donné les messages de commit.
À la manière des emails dont les messages sont inspirés, un message de commit se décompose en 2 parties: le titre et un corps. Le titre s'inspire des sujets pour les emails tandis que le corps s'inspire du corps des emails. Le corps du message peut contenir plusieurs paragraphes de texte qui apportent toutes les infos nécessaire à la compréhension du commit. Le corps du message peut se terminer par un pied de page où sont repris différentes meta-informations, par exemple une liste de co-contributeurs, des notes en bas de page ou encore des références vers des numéros de tickets ou des issues.
type(scope): titre sous 50 caractères............
Corps avec plusieurs paragraphes, chaque ligne sous 72 caractères et...
qui rappelle le contexte, explique pourquoi les changements sont.......
nécessaires et apporte des éclairsissements si le code est compliqué...
Après le corps on peut retrouver une série de références, notez que....
certains [mots-clés] sont automatiquement reconnus par github..........
[mots-clés]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests
Le titre doit être un résumé concis et de préférence sous 50 caractères du contenu du commit. Normalement, il s'agit d'une phrase à l'infinitif en français (à l'impératif en anglais) qui peut compléter la phrase "Thanks to this commit we can ...", par exemple "Thanks to this commit we can fix bad smtp To headers for unicode addresses".
Selon les organisations, les titres des commits peuvent suivre un format précis où le type du changement et l'endroit du changement doivent être systématiquement écris. Par exemple en suivant la convention de contentional commits, le précédent titre deviendrait "fix(smtp): bad To header for unicode addresses". En suivant la convention en vigueur à Odoo, il deviendrait "[FIX] smtp: bad To headers for unicode addresses".
Le corps du message est la partie la plus importante, c'est dans cette partie que sont formellement décrits tous les changements que le commit apporte. C'est aussi, malheureusement, la partie la moins comprise et la plus souvent ignorée par les novices de git.
Là où la diff qui accompagne le message de commit explique formellement comment et où dans le code les changements ont été effectués, le corps du message de commit doit formellement expliquer qu'est-ce qui et pourquoi ça a été changé.
Il est inutile de répéter dans le message de commit ce qui peut être appris en lisant soit le titre soit la diff. Ceci implique qu'un effort a été réalisé pour rédiger du code propre et correctement documenté avec des docstrings et des commentaires. Il est parfois judicieux de profiter du message de commit pour rappeler comment une fonctionnalité a évoluée au fil du temps, pour justifier l'état actuel du code source avec des explications historiques qui n'ont pas vraiment leur place ni en docstring ni en commentaire mais il ne faut pas expliquer le code. Lorsqu'on ressent le besoin d'expliquer la diff, c'est peut-être une indication que le code n'est pas très propre.
Dans le corps du message, il faut donc se concentrer à apporter les informations qui ne peuvent pas être comprises en lisant seulement la diff. Il faut notamment donner un bref rappel des fonctionnalités en cours de modification pour donner le contexte générale, une vue d'ensemble. Il faut aussi impérativement expliquer pourquoi les changements ont été réalisé, paraphraser les spécifications dans le cas d'une nouvelle fonctionnalité ou bien donner les étapes pour reproduire un bug qui a été corrigé.
En pied de page (footer, trailer) peuvent se trouver toutes une série de méta-information libres au format "Clé: valeur". On y retrouve:
- Les URLs pour tous les liens présents dans le corps du message.
- Les références vers les issues et les PR de Github.
- Les références vers les tâches ou les tickets dans les autres logiciels de gestion.
- Les références vers les autres commits liés au commit présent.
- Le nom des co-auteurs et de ceux qui ont review.
Dans le cas où notre commit est lié au ticket numéro 123 dans Jira et qu'il vient également clôturer l'issue 172 et la pull-request 173 dans Github, on écrira:
Closes: #172
Closes: #173
JRA-123
Notez que pour éviter que le numéro d'un ticket dans un logiciel externe soit reconnu (à tord) comme le numéro d'une issue ou d'une PR dans Github, la convention est d'accoler le numéro avec un tiret plutôt que deux-points.
Dans le cas où notre commit est en relation avec un commit provenant d'une autre branche ou d'un autre projet, on écrira:
Reference-to: orga/repo:1a2bc3 (fix bad smtp To header for unicode address)
Dans le cas où notre collègue John Doe nous a beaucoup aidé dans la conception ou la réalisation du travail et qu'on souhaiter l'accréditer, on écrira:
Co-authored-by: John Doe <john.doe@example.com>
Comme ces champs sont libres, il n'existe pas de registre officiel où l'ensemble des clés possibles sont regroupés. Ces quelques précédents exemples ne sont que quelques exemples assez répandu.
Nous pouvons aussi citer Helper-By, Acked-By et Signed-off-by pour
respectivement accréditer quelqu'un qui a aidé pendant le développement, ceux
qui ont review la PR et celui qui prend la responsabilité légale des
changements.
Les commits et leurs messages sont lus à trois occasions différentes. Lors de la review par les reviewers, par intérêt général par les curieux qui lisent régulièrement l'historique pour se tenir au courant des modifications et au final par les collègues qui se creuse la tête au moment de debugger un bout de code qu'ils ne comprennent pas.
Lors de la review, les reviewers doivent comprendre l'ensemble des changements et les valider quant aux fonctionnalités qui étaient spécifiées. Ils étudient les changement en lisant scrupuleusement chaque ligne de code et en testant les nouvelles fonctionnalités. Le but de la review est de s'assurer que le travail est bien fait, de vérifier qu'il n'y a pas de bug et d'ouvrir une discussion pour proposer des améliorations avant que le code ne soit validé et mergé.
Pour ouvrir une discussion constructive, il est donc important que les reviewers comprennent l'ensemble des changements apportés au code. Le message de commit doit leur permettre d'avoir une vue d'ensemble de ce qui est modifié de sorte à ce qu'il n'y ait pas de surprises, pas de moments "WTF?!", lorsqu'ils liront le code la première fois.
Ceci implique que le code doit être soigné et correctement structuré pour inviter des commentaires plus de font que de formes. Ceci implique aussi que les reviewers doivent avoir une vue d'ensemble de ce qui est modifié et des comprendre les décisions qui ont été prises au moment du développement. C'est ici qu'intervient le message de commit. En rappelant le contexte générale et en justifiant les choix techniques.
Lorsque le message de commit est manquant, incomplet ou qu'il n'est correctement rédigé, les reviewers se retrouvent alors dans une situation où ils doivent beaucoup plus travailler pour comprendre ce qu'il se passe. Ils doivent relire l'ensemble des discussions autours de la spécification originale (si une telle spécification existe) et passer beaucoup plus de temps sur le code. Il y a alors un risque non négligeable que le reviewer ne prenne pas ce temps nécessaire et se contente d'une review minimale... avec son lot de répercutions sur la dette technique. Cette situation est bien reprise dans le short suivant, même s'il devrait plutôt être labellisé "how we write/review code in shit companies": https://youtube.com/shorts/0xB3T4MPEr0.
Le second moment où les messages de commit s'avèrent utiles est lorsqu'il
s'agit d'étudier un bout de code, de comprendre le fonctionnement d'un fonction
au travers du git blame.
git blame est une commande qui permet d'associer chaque ligne de code d'un
fichier avec le commit qui en dernier a modifié la ligne. Il est alors possible
d'étudier les changements qui ont été opéré sur une fonction pour mieux en
comprendre son fonctionnement.
Le plus souvent cet outil est utilisé lorsqu'un bout de code est "WTF?!", que quelques lignes de codes sortent de l'ordinaire, contrastent avec le reste d'une fonction sans qu'aucun commentaire/docstring ne l'explique, ou bien qu'il y a bel et bien un commentaire mais que celui-ci reste trop succins.
Le moment où une personne étudiera l'historique au travers du git blame sera
souvent complètement déconnecté du moment où les changements auront été
commités. On peut parler ici d'une différence allant même jusqu'à plusieurs
années. Il est donc important de s'assurer au moment de créer les commits que
chaque ligne dans la diff puisse être comprise via le message de commit. Il
faut donc résister à l'envie de créer un seul gros commit pour plusieurs
changements orthogonaux (des changements qui n'ont pas grand chose à voir les
uns avec les autres) et au besoin isoler chaque groupe de changement dans des
commits séparés. Il est d'ailleurs tout à fait acceptable d'avoir plusieurs
commits dans une même pull-request pour profiter d'une seule review pour
l'ensemble des changement tout mais de tout de même correctement segmenter le
travail en prévision d'un futur git blame.
Le dernier moment où quelqu'un est susceptible de lire les message de commit est lorsque cette personne s'intéresse à l'historique en générale pour se tenir au courant des changement récent. C'est principalement le cas dans les petites équipes, lorsqu'il y est encore humainement faisable de se tenir au courant de l'ensemble des modifications apportées au projet. La plupart des bibliothèques open-source évoluent d'ailleurs suffisamment lentement pour qu'il soit possible de se tenir à jour des changement d'API.
Au moment d'écrire un message de commit, si le travail contient une nouvelle fonctionnalité ou un changement d'API, il est intéressant de rédiger un résumé explicatif des nouvelles fonctionnalités et de clairement expliquer tout changement d'API avec des exemples claires.
Déterminer la qualité générale d'un message de commit ou plus généralement d'un historique git est assez subjectif. Il n'y a pas de recette miracle pour améliorer sa rédaction en dehors de pratiquer régulièrement et de prendre la peine de s'auto-évaluer. Un exercice utile peut être de se porter régulièrement volontaire pour faire des reviews de pull-requests et de porter un regard attentif au message de commit. À force de faire des reviews, vous apprendrez à reconnaitre ce qui est utile, nécessaire, voir même précieux dans l'ensemble de la paperasse (spec, message de commit, documentation, docstrings, commentaires, ...) et à reprendre les bons exemples et éviter les mauvais.
Vous pouvez vous poser la question quant à la fréquence à laquelle vous arrivez
à travailler en autonomie en parcourant l'historique à travers de git blame
ou de vous maintenir à jour en lisant le git log. Si vous n'arrivez jamais à
trouver les informations que vous cherchez ni avec blame, ni avec log, c'est
certainement que l'historique et les commits ne sont pas bons. Si au contraire
vous vous retrouvez régulièrement à naviguer dans l'historique, c'est
certainement que le travail est bien fait.
La rédaction des messages de commit fait parti intégrante du métier de développeurs et vient, à l'instar de l'écriture des tests unitaires, différencier le développeur amateur du développeur professionnel.
Les messages de commit sont le cœur de la documentation technique à destination des mainteneurs. Ils sont écris pour les collègues d'aujourd'hui qui devront aussi bien valider notre travail via les pull-requests, ils sont aussi écrits pour les collègues de demain qui devront étudier notre code pour le faire évoluer.
Grâce aux messages de commit, il est possible de retracer l'évolution d'un logiciel et de développer sa propre compréhension des différentes étapes qui l'ont mener à être ce qu'il est aujourd'hui. Il s'agit d'un atoux précieux qui renforce la confiance des développeurs quant aux changements qu'ils apportent au logiciel.