Mon commit Git préféré (2019)

Mon commit Git préféré

• L’article souligne l’importance des messages de commit Git et les considère comme l’un des outils les plus puissants pour documenter une base de code.
• Il explique pourquoi en prenant comme exemple le commit de Dan Carley intitulé "Convert template to US-ASCII to fix error".
• En s’appuyant sur son expérience au GDS (Government Digital Service), l’auteur explique que l’un des avantages du développement en public est de pouvoir partager ce type d’exemples au-delà de l’organisation.

Pourquoi ce commit est remarquable

• Le rapport entre la longueur du message de commit et les changements de code est amusant, mais ce n’est pas pour cela qu’il mérite d’être partagé.
• Dans une autre organisation, ou par un autre développeur, ce message de commit aurait pu se résumer à change whitespace ou fix bug.
• À la place, Dan a pris le temps d’écrire un message de commit réellement utile pour les personnes qui l’entourent.

Il explique la raison du changement

• Les meilleurs messages de commit expliquent non seulement ce qui a été modifié, mais aussi pourquoi cela l’a été.
• Dans ce commit, il détaille pourquoi le test ajouté pour faire correspondre le contenu de /etc/nginx/router_routes.conf échouait avec l’erreur ArgumentError: invalid byte sequence in US-ASCII lorsqu’il était exécuté via bundle exec rake.
• Ce type d’information est extrêmement précieux à documenter, et peut facilement se perdre lorsque le contexte initial est oublié, que des personnes changent d’équipe ou quittent l’organisation.

Il est facile à rechercher

• La première partie du message de commit contient le message d’erreur à l’origine du changement, ce qui permet à n’importe qui d’exécuter git log --grep "invalid byte sequence" dans la base de code ou d’utiliser la recherche de commits sur GitHub pour retrouver cette erreur.
• En pratique, plusieurs personnes ont effectivement recherché ce problème et ont pu découvrir qui l’avait déjà rencontré et comment il avait été traité.

Il raconte une histoire

• Le message de commit contient des détails sur la manière dont le problème s’est manifesté, sur le déroulement de l’enquête et sur le processus de résolution.
• Les messages de commit ne servent pas seulement à documenter un fichier, une fonction ou une ligne de code précise ; ils sont aussi particulièrement adaptés pour consigner des informations supplémentaires sur le parcours de la base de code.

Il rend tout le monde un peu plus compétent

• Le fait que Dan ait documenté les commandes exécutées à chaque étape peut constituer une manière légère de partager les connaissances au sein de l’équipe.
• En lisant ce message de commit, quelqu’un peut apprendre quelques astuces utiles sur l’outillage Unix.
• Qu’il s’agisse de la personne qui relit ce changement ou de celle qui retrouvera plus tard ce commit, toutes peuvent en tirer quelque chose.

Il construit de l’empathie et de la confiance

• Le dernier paragraphe ajoute un contexte humain.
• À sa lecture, on peut ressentir la frustration de Dan après avoir passé une heure à traquer un bug retors, ainsi que sa satisfaction une fois le problème résolu.
• Ce type de message de commit aide à se souvenir que derrière chaque changement se trouve une personne qui a pris la meilleure décision possible.

L’importance des bons commits

• Cet exemple est un cas extrême, et il ne faut pas s’attendre à ce que tous les commits aient un tel niveau de détail.
• Il s’agit néanmoins d’un excellent exemple de la manière d’expliquer le contexte d’un changement, d’aider les autres à apprendre, et d’enrichir le modèle mental collectif de l’équipe à propos de la base de code.
• Pour aller plus loin sur les bénéfices des bons messages de commit et sur les outils qui aident à mieux les structurer, l’auteur recommande "Telling stories through your commits" de Joel Chippindale et "A branch in time" de Tekin Süleyman.

Avis de GN⁺

• Cet article met en avant l’importance des messages de commit Git et montre à quel point ils peuvent être un outil puissant pour documenter l’historique d’une base de code et partager les connaissances.
• Le message de commit de Dan Carley constitue un exemple remarquable à plusieurs égards : explication des raisons du changement, facilité de recherche, narration, partage des connaissances, et construction d’empathie et de confiance.
• En comprenant et en appliquant l’importance de la rédaction de bons messages de commit, les développeurs peuvent améliorer la collaboration et la maintenance du code, ce qui peut contribuer à accroître la productivité et l’efficacité de l’ensemble de l’équipe.

[GN⁺]

Avis Hacker News

• Avis du cofondateur de GitHub :

  • Les messages de commit Git constituent une manière particulière de documenter le code, mais ce n’est pas un système optimisé.
  • La plupart des outils n’affichent que la première ligne du message de commit.
  • Git a conçu les messages de commit pour qu’ils puissent être lus par tous les participants au projet, comme le corps d’un e-mail, mais en pratique ils sont rarement consultés.
  • Il est aussi difficile de retrouver le message de commit pertinent avec git blame.
  • Les messages de commit du projet Git sont très détaillés, mais en pratique ils sont peu exploités.
  • Produire une excellente documentation via Git revient presque à une perte de temps dans la plupart des communautés.

• L’importance des messages de commit pour des problèmes précis :

  • La première ligne d’un message de commit, lorsqu’elle explique clairement le problème, est importante.
  • Le reste peut être lu pour obtenir des informations supplémentaires si nécessaire.

• Sentiment personnel à propos des messages de commit :

  • Il y a une certaine fierté à écrire d’excellents messages de commit, mais il n’est pas certain qu’ils aient de la valeur pour les autres.
  • La plupart des gens recherchent très rarement dans les messages de commit.
  • Un beau message de commit peut relever de la vanité du programmeur et n’avoir aucune valeur concrète.

• Stratégie pour écrire la première ligne d’un message de commit :

  • Lorsqu’on utilise git log, la première ligne est la plus importante.
  • La première ligne doit indiquer non pas ce qui a été fait, mais pourquoi cela a été fait.
  • Comme dans un article de presse, il vaut mieux présenter d’abord l’information la plus importante, puis aller vers le détail.

• La difficulté de modifier les messages de commit :

  • Les messages de commit sont difficiles à modifier une fois écrits.
  • Les documents comme les fichiers .md, les wikis ou Confluence sont faciles à corriger.
  • Il vaut mieux résister à la tentation d’expliquer la conception d’un composant dans le commit et améliorer la documentation si nécessaire.

• L’importance d’explications détaillées pour les petits commits :

  • Plus un commit est petit, plus il peut nécessiter une explication relativement longue.
  • Il est important d’expliquer en détail la raison de petits changements.

• Les limites des messages de commit et les problèmes des outils :

  • Il faut rédiger la première ligne des messages de commit de manière plus précise.
  • Le reste d’une longue explication peut ne pas avoir beaucoup de valeur.
  • Cela souligne aussi des problèmes dans les outils de développement, notamment le besoin de messages d’erreur plus clairs.
  • Cela soulève la question de savoir pourquoi les outils d’édition de code autorisent des caractères d’espacement non standard.

• L’importance de l’hygiène des commits par rapport aux messages de commit :

  • Une bonne hygiène de commit est plus importante que le niveau de détail des messages.
  • Des commits propres et indépendants permettent d’extraire et de réutiliser plus facilement les fonctionnalités du code.

• Critique de l’auto-squash et du rebase :

  • L’auto-squash empêche d’écrire des messages de commit réellement significatifs.
  • Le rebase est fait pour permettre aux développeurs de réorganiser volontairement leur historique, et ne devrait pas devenir le modèle par défaut au moment du merge.