11 conseils pour écrire un bon message de commit Git

Dernièrement, j’ai porté une plus grande attention aux journaux des modifications que je reçois des produits et services lorsque des mises à jour sont nécessaires. Voici quelques exemples:

• Correction de quelques bogues.
• Améliorations apportées à l’accessibilité.
• Nous avons apporté des améliorations et corrigé des bugs pour une conduite plus fluide.

Quand je pense à certains des premiers messages de commit que j’ai faits en tant que développeur junior, je dois baisser la tête avec consternation :

• Pointé et cliqué un peu et maintenant les choses semblent fonctionner.
• J’ai fait ce que le programmeur X m’a dit de faire et maintenant la bannière est bleue.

Cela peut être frustrant ! J’ai posé à notre communauté de contributeurs les questions suivantes :

• Qu’est-ce qui fait un bon message de commit Git ?
• Qu’est-ce qui en fait un mauvais ?
• Selon vous, quelles règles un projet devrait-il avoir concernant le contenu d’un message de validation ?

Voici leurs réponses :

Une bonne écriture est la clé

Comme pour tout ce que vous écrivez, vous devez penser à qui va le lire. Adaptez ensuite la quantité et la profondeur des informations en conséquence.

Améliorer vos compétences en langage naturel et en écriture est essentiel pour une carrière saine dans le développement de logiciels. Il n’y a pas que le code qui compte.

—Camilla Conté

Soyez descriptif et ne présumez pas

Je passe beaucoup de temps à collaborer avec la communauté OpenStack, et ses réviseurs de code ont des normes assez exigeantes par rapport à ce que je vois d’autres projets “dans la nature”.

Je passe souvent beaucoup plus de temps à composer un message de validation solide qu’à écrire l’implémentation ou le correctif du code réel. Parfois, les messages de validation peuvent être plusieurs fois plus longs que les différences qu’ils expliquent.

Pour résumer certains des conseils aux contributeurs :

• Décrivez pourquoi un changement est apporté, pas seulement ce qui change
• La première ligne de commit est la plus importante (comme la ligne d’objet d’un e-mail)
• Ne présumez pas que les examinateurs comprennent le problème initial que vous résolvez
• Ne présumez pas que l’examinateur a accès à des services Web externes ou au site (résumez les rapports de défauts et autres discussions pertinentes)
• Ne présumez pas que le code est évident et auto-documenté (bien qu’il ne soit pas nécessaire de répéter les points que vous faites également dans vos commentaires de code)
• N’incluez pas d’informations uniquement pertinentes pour les révisions précédentes de la modification (nous attendons des contributeurs qu’ils regroupent les révisions et modifient leurs messages de validation en conséquence).

Il y a une brève section sur le sujet dans le Guide des contributeurs d’OpenStack : https://docs.openstack.org/contributors/common/git.html#commit-messages

—Jérémy Stanley

Votre futur moi vous remerciera

Je ne peux pas être plus d’accord avec Jeremy. +1000

Jeremy a dit, “décrivez pourquoi un changement est apporté, pas seulement ce qui change.”

Imaginez que vous êtes quelqu’un d’autre, dans un futur lointain, essayant d’élaborer ce commit.

Mettez-vous à la place des autres, comme le dit le vieil adage.

—Leigh Morresi

Utiliser l’identifiant du bogue

Je recommande d’ajouter l’ID de bogue au début du message de validation afin qu’il soit plus facile de suivre les validations ultérieurement à l’aide de la grep commande.

Par exemple:

$ git commit -m "BZ#19xxxxx 

Pour proposer des commits réfléchis, considérez ce qui suit :

• Pourquoi ai-je apporté ces modifications ?
• Quel effet mes modifications ont-elles apportées ?
• Pourquoi le changement était-il nécessaire ?
• A quoi font référence les changements ?

—Agil Antoine

Racontez toute l’histoire

J’aime imaginer qu’il y a un préfixe caché dans chaque message de validation qui se lit “En appliquant ceci”.

Un bon message de commit inclut exactement ce qui va se passer et pourquoi. Il ne suffit pas d’avoir simplement la référence du ticket de travail car cela décentralise l’information ; Git est décentralisé. En tant que développeur de logiciels, je veux savoir pourquoi les modifications proposées sont envisagées. Quel problème spécifique est traité ? Quelles solutions alternatives ont été envisagées (et rejetées) ? Quelles choses inattendues ont été découvertes lors de la création de l’ensemble de modifications qui ont influencé le contenu actuel ?

Il n’y a pas de prix pour le message de commit le plus court. Votre futur vous-même et vos futurs collègues apprécieront que vous expliquiez en profondeur le problème et pourquoi cet ensemble de modifications est la réponse. Exploitez ces blogs de cuisine où il y a une histoire de vie en cinq paragraphes. Ici, cependant, faites du problème le sujet de l’histoire de la vie.

—Lisa Seelye

Mais ne soyez pas trop verbeux

Un bon message de validation git contient des informations sur ce qui a été fait, et rien d’autre. Par exemple, si vous avez besoin de mettre à jour le .gitignore, dites simplement “mis à jour .gitignore”. Les gens peuvent plonger dans le commit lui-même pour plus de détails. Il n’a pas besoin d’être verbeux.

Un mauvais message de commit est quelque chose comme “oh merde” ou “essaye ça”. Certes, j’ai été coupable de cela, mais cela n’aide personne s’il a besoin de regarder les commits en un coup d’œil.

Les règles sont très subjectives. Ils peuvent différer d’un prospect à l’autre et d’une équipe à l’autre. Mais à tout le moins, donnez des informations contextuelles sur le commit. Surtout si c’est un grand. Personne n’a le temps de parcourir plus de 1000 fichiers avec un lourd historique de modifications.

— Miriam Goldman

Utilisez le présent

J’aime les messages de validation de style chef de projet écrits en termes présents et non futurs (par exemple, “ajouter” au lieu de “ajouter”). Cependant, cela n’est généralement possible que si les commits sont fréquents. Il y a tellement de “comment ai-je fait” dont vous pouvez vous souvenir lorsque vous êtes confronté à une échéance. Pourtant, des commits bien écrits aident non seulement les collaborateurs, mais sont également utiles au committer pour se souvenir de l’histoire.

—Chris Okpada

Ne vous fiez pas aux liens

Une chose que j’aime rappeler à mes collègues est que vous ne vous contentez pas d’expliquer aux personnes qui vont décider d’approuver ou non votre engagement. Vous expliquez également aux futurs développeurs et utilisateurs qui ont trouvé ce commit dans une opération de bisect ou de blâme et qui essaient de comprendre sa pertinence.

Si le seul contexte fourni est un lien vers un système externe et que, dans le futur, le système auquel il est lié n’est plus utilisé ou est devenu inaccessible pour cette personne, votre message de validation a été rendu inutile et peut tout aussi bien être vide.

Trop souvent, je vais fouiller dans l’historique Git d’un projet open source et je trouve des messages de validation qui ne sont rien de plus qu’un ID de bogue ou un lien vers le traqueur de défauts interne et privé d’une entreprise.

Ne soyez pas ce projet !

—Jérémy Stanley

Changelogs clairs et concis

En tant que responsable des communications sur les versions, je lis souvent l’intégralité du tableau des versions. J’ai également rencontré des développeurs pour discuter de tous les domaines qui n’étaient pas encore clairs. Ensuite, j’ai testé la version tôt. Après cela, j’écrirais un article de version en recherchant les journaux des modifications et le contenu révisé ou nouveau correspondant.

Les journaux des modifications sont des rappels personnels pour les développeurs, mais ils ont également des problèmes et des tickets correspondants pour eux. Vous devez mettre correctement les noms de produits en majuscules, utiliser un correcteur orthographique, être cohérent avec la ponctuation et la structure des phrases. Le développeur principal doit également les relire. Vos clients, qui sont des développeurs, les lisent. Quelles informations doivent-ils connaître avant d’exécuter la mise à jour pour mieux servir leurs clients ?

—Courtney Robertson

Être spécifique

En tant que responsable de publication fréquent, j’aime les messages qui nomment le composant touché par un commit et une brève description de ce qui a été modifié. Avoir également une référence à l’origine de la demande de ce travail aide à lier les correctifs longtemps après que nous ayons oublié le nom de votre branche intelligente.

• “réparer l’erreur fatale” n’est pas idéal.
• “ISS-304 : correction d’une erreur fatale dans la fonction de contrôle d’accès à la connexion pour les utilisateurs
  avec le rôle Partenaire”, c’est mieux.
• “ISS-304 : Contrôle d’accès à la connexion : correction d’une erreur fatale dans getPartnerId()” est
  mieux encore.

Je peux examiner l’intégralité de la relation entre un commit Git, une branche, un commit de fusion et inspecter les lignes et les fichiers individuels qui ont été modifiés. Mais je n’ai pas ce genre de temps au milieu d’une sortie. Je veux pouvoir me rapporter à la source de ce travail dans l’outil de gestion de projet, avoir une idée des composants qui sont modifiés et de quelle manière.

—Ryan Price

Faites-en une habitude

Mon commit préféré dont je suis coupable est “commit avant de changer de branche” parce que je dois travailler sur autre chose de plus urgent. Parfois, je dois consacrer mon travail actuel à un projet totalement différent. La stratégie de mon manager est de nous faire travailler comme nous le faisons normalement. Mais ensuite, lorsque nous rebasons, il veut que nous écrasions les commits là où cela a du sens et écrivions de meilleurs messages. Je ne peux pas dire que nous le fassions toujours, mais sa méthode a du sens.

J’ai aussi beaucoup de messages de type “c’est cassé, je ne sais pas pourquoi” (haha) où j’essaie des choses mais je veux valider cette tentative avant d’essayer autre chose au cas où la méthode A serait plus proche de résoudre le problème que la méthode B. L’écriture de code est un gâchis chaud. Et je l’écris depuis plus de 10 ans.

—Rachie Vee

Quels conseils ou astuces de message de commit vivez-vous ? Faites le nous savoir dans les commentaires.