Mon git commit préféré

Remarque perev. : Cette publication d'un programmeur britannique, qui est devenu un véritable succès sur Internet anglophone, fait référence à un engagement de Git il y a 6 ans. Il a été enregistré dans l'un des référentiels ouverts du service numérique du gouvernement - un service dédié au développement de services numériques au Royaume-Uni et soutenant le projet GOV.UK. Le commit lui-même est intéressant non pas tant avec les modifications du code qu'avec la description qui les accompagne ...


Image de xkcd # 1296

J'adore les descriptions de commit dans Git. Lorsqu'ils sont utilisés correctement, ils peuvent être appelés l'un des outils les plus puissants pour documenter l'évolution de la base de code au cours de son existence. Je veux illustrer mon point de vue avec l'exemple de ma description préférée.

Cet engagement remonte à l'époque où je travaillais chez Government Digital Service. Son auteur est un développeur nommé Dan Carley , et il a un titre plutôt banal: " Converti le modèle en US-ASCII pour corriger l'erreur ."

«J'ai implémenté plusieurs tests dans la branche des fonctionnalités pour faire correspondre le contenu de« / etc / nginx / router_routes.conf ». Ils fonctionnaient bien s'ils étaient exécutés avec les commandes `bundle exec rake spec` ou` bundle exec rspec modules / router / spec`. Mais lors de l'exécution de `bundle exec rake`, chaque bloc devrait échouer:

ArgumentError: invalid byte sequence in US-ASCII 

Au final, j'ai trouvé qu'après l'exception à l'expression `.with_content (//)`, toutes les erreurs disparaissent. Qu'il n'y a pas de caractères étranges dans le fichier de spécifications. Et aussi qu'il peut être joué en appelant Puppet dans le même interprète:

  rake -E 'require "puppet"' spec 

Ce modèle semble être le seul fichier de notre base de code encodé avec 'utf-8'. Tous les autres fichiers de 'us-ascii':

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

Une tentative de transcodage en US-ASCII a échoué en raison d'un seul caractère qui ressemble à un espace:

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

Après l'avoir remplacé (manuellement), le fichier est redevenu 'US-ASCII':

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

Maintenant, les tests fonctionnent! L'heure entière de ma vie ne peut pas être restituée ... "

Une petite digression: l'un des avantages du développement open source pratiqué dans GDS est que vous pouvez partager des exemples comme celui-ci en dehors de l'organisation qui les a créés. Je ne sais pas qui a proposé ce concept à GDS pour la première fois - au moment où j'ai rejoint l'organisation, il était déjà largement utilisé - mais je suis infiniment reconnaissant envers cette personne.

Pourquoi j'aime ce commit

D'innombrables fois, je l'ai cité comme un exemple de ce dont les descriptions de commit sont capables. C'est un peu drôle à cause du ratio de changements dans le code et de la taille de la description, mais je ne l'aime pas du tout.

Dans une autre entreprise, avec un autre développeur, le message entier du commit pourrait être réduit à des phrases comme «remplacé l'espace», «corrigé l'erreur» ou (selon la culture de l'équipe) à des attaques contre l'inventeur d'espaces inextricables. Au lieu de cela, Dan a pris le temps de créer une description détaillée utile aux autres. Je voudrais m'attarder sur les raisons pour lesquelles je considère cet engagement comme un très bon exemple.

Divulgue la raison des changements

Les meilleures descriptions de commits indiquent non seulement ce qui a changé, mais expliquent également pourquoi . Dans notre cas:

J'ai implémenté plusieurs tests dans la branche des fonctionnalités pour faire correspondre le contenu de `/ etc / nginx / router_routes.conf`. Ils fonctionnaient bien s'ils étaient exécutés avec les commandes `bundle exec rake spec` ou` bundle exec rspec modules / router / spec`. Mais lors de l'exécution de `bundle exec rake`, chaque bloc devrait échouer:

  ArgumentError: invalid byte sequence in US-ASCII 

Sans un tel niveau de détail, nous pourrions supposer que la validation a corrigé l'erreur d'analyse dans un outil particulier. Grâce à la description du commit, nous savons de quel type d'outil il s'agissait.

Ce type d'informations peut s'avérer très utile et il est trop facile à perdre, car les gens ont tendance à oublier les subtilités de leur travail, à passer à d'autres équipes et, finalement, à quitter l'entreprise.

Bon pour la recherche

L'un des éléments clés de cette description est l'erreur elle-même, avec laquelle de nouvelles recherches ont commencé:

ArgumentError:
séquence d'octets invalide en US-ASCII

Quiconque rencontre cette erreur peut rechercher la base de code, soit en exécutant git log --grep "invalid byte sequence" , soit en utilisant la recherche de git log --grep "invalid byte sequence" GitHub . En fait, à en juger par les résultats de la recherche, beaucoup l'ont déjà fait et ont découvert qui et quand faire face à ce problème et comment il a finalement été résolu.

Fournit une image complète

Le message de validation détaille l'apparence du problème, la manière dont il a été étudié et résolu. Par exemple:

Au final, j'ai trouvé qu'après l'exception à l'expression `.with_content (//)`, toutes les erreurs disparaissent. Qu'il n'y a pas de caractères étranges dans le fichier de spécifications. Et aussi qu'il peut être joué en appelant Puppet dans le même interprète.

C'est l'un des domaines dans lesquels les messages lors des validations sont vraiment capables de s'afficher, car ils décrivent le changement lui-même, et non un fichier, une fonction ou une ligne de code. Cela en fait un endroit idéal pour stocker ce type d'informations d'aventure de base de code supplémentaires.

Rend tout le monde un peu plus intelligent

Dan a fait une chose ici, que j'apprécie vraiment: faire venir toutes les équipes que j'ai exécutées à chaque étape. Il s'agit d'un excellent moyen abordable de partager des connaissances en équipe. En lisant sa description du commit, vous pouvez en apprendre beaucoup sur les outils Unix:

• vous pouvez passer l'argument -exec pour find pour exécuter une commande avec chaque fichier trouvé;
• ajouter \+ à la fin de la commande fait quelque chose de très intéressant (transmet plusieurs noms de fichier à la commande file et n'exécute pas la commande une fois pour chaque fichier);
• file --mime permet de connaître le type MIME du fichier;
• il y a un utilitaire iconv .

Une personne qui regarde une description peut en apprendre davantage sur toutes ces choses. Quiconque tombe sur ce commit plus tard en apprendra également davantage sur ces choses. Si vous multipliez cette approche pour des engagements sur une longue période et un nombre suffisant d'entre eux, cela peut devenir un puissant stimulant pour l'équipe.

Développe l'empathie et la confiance

Maintenant, les tests fonctionnent! L'heure entière de ma vie ne peut être restituée ...

Le dernier paragraphe ajoute un minimum d'humanité. En lisant ces mots, il est difficile de ne pas ressentir la déception de Dan, qui a dû passer une heure entière à chercher une erreur cachée, et la satisfaction de la corriger.

Imaginez maintenant un message similaire attaché à un hack temporaire ou à un fragment du code prototype qui est entré en production et «a pris racine» (comme c'est souvent le cas avec de tels fragments). Cette description du commit rappelle à chacun que derrière chaque changement se trouve une personne qui prend la meilleure décision possible, compte tenu des informations disponibles à ce moment-là.

Les bons engagements comptent

J'avoue que c'est un exemple extrême, et je ne m'attends pas à ce que tous les commits (en particulier d'une telle portée) offrent le même niveau de détail. Cependant, je pense toujours que c'est un excellent exemple pour expliquer la raison du changement, aider les autres à apprendre de nouvelles choses et contribuer au modèle mental collectif associé à la base de code.

Si vous voulez en savoir un peu plus sur les avantages d'une bonne description des validations et sur certains outils qui facilitent la structuration des modifications, je peux recommander les matériaux suivants:

• « Raconter des histoires à travers vos commits » par Joel Chippindale;
• " Une branche dans le temps " par Tekin Süleyman.

PS du traducteur

Lisez aussi dans notre blog:

• « Git arrive! 6 erreurs Git typiques et comment les corriger ";
• «Une merveilleuse astuce pour faire un mainteneur de projet open source par jour »;
• « Qu'ont en commun les grands projets Open Source réussis? ".