Messages Git Commit: formatage 50/72

Tim Pope plaide pour un style de message de commit Git particulier dans son article de blog: http://www.tpope.net/node/106 .

Voici un bref résumé de ce qu'il recommande:

• La première ligne contient 50 caractères ou moins.
• Puis une ligne vierge.
• Le texte restant doit être composé de 72 caractères.

Son article de blog donne la justification de ces recommandations (que j'appellerai «formatage 50/72» par souci de concision):

• Dans la pratique, certains outils traitent la première ligne comme une ligne d'objet et le deuxième paragraphe comme un corps (similaire au courrier électronique).
• git log ne gère pas l'habillage, il est donc difficile de lire si les lignes sont trop longues.
• git format-patch --stdout convertit les validations en e-mail - donc pour jouer bien, cela aide si vos validations sont déjà bien emballées.

Je voudrais ajouter un point sur lequel je pense que Tim serait d'accord:

• Le fait de résumer votre commit est une bonne pratique inhérente à tout système de contrôle de version. Il aide les autres (ou plus tard vous) à trouver plus rapidement les commits pertinents.

Donc, j'ai quelques angles de vue avec ma question:

• Quelle partie (approximative) des «leaders d'opinion» ou des «utilisateurs expérimentés» de Git adoptent le style de formatage 50/72? Je pose cette question parce que parfois les nouveaux utilisateurs ne connaissent pas ou ne se soucient pas des pratiques communautaires.
• Pour ceux qui n'utilisent pas cette mise en forme, existe-t-il une raison de principe pour utiliser un style de mise en forme différent? (Veuillez noter que je recherche un argument sur le fond, pas «je n'en ai jamais entendu parler» ou «je m'en fiche».)
• Empiriquement parlant, quel pourcentage des référentiels Git adoptent ce style? (Au cas où quelqu'un voudrait faire une analyse sur les référentiels GitHub… indice, indice.)

Mon point ici n'est pas de recommander le style 50/72 ou d'abattre d'autres styles. (Pour être ouvert à ce sujet, je le préfère, mais je suis ouvert à d'autres idées.) Je veux simplement savoir pourquoi les gens aiment ou s'opposent à divers styles de message de validation Git. (N'hésitez pas non plus à évoquer des points qui n'ont pas été mentionnés.)

Concernant la ligne «résumé» (le 50 dans votre formule), la documentation du noyau Linux a ceci à dire :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Cela dit, il semble que les responsables du noyau essaient effectivement de maintenir les choses autour de 50. Voici un histogramme des longueurs des lignes de résumé dans le journal git pour le noyau:

( voir en taille réelle )

Il y a une poignée de validations qui ont des lignes de résumé plus longues (certaines beaucoup plus longues) que ce tracé ne peut contenir sans que la partie intéressante ressemble à une seule ligne. (Il y a probablement une technique statistique sophistiquée pour incorporer ces données ici, mais bon… :-)

Si vous voulez voir les longueurs brutes:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

ou un histogramme textuel:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

Concernant les «leaders d'opinion»: Linus préconise avec insistance le retour à la ligne pour le message de validation complet:

[…] Nous utilisons des colonnes de 72 caractères pour le retour à la ligne, sauf pour le matériel cité qui a un format de ligne spécifique.

Les exceptions se réfèrent principalement au texte «non-prose», c'est-à-dire au texte qui n'a pas été tapé par un humain pour la validation - par exemple, les messages d'erreur du compilateur.

La séparation de la présentation et des données entraîne mes messages de validation ici.

Votre message de validation ne doit pas être intégré à un nombre de caractères et à la place, les sauts de ligne doivent être utilisés pour séparer les pensées, les paragraphes, etc. dans le cadre des données, et non de la présentation. Dans ce cas, les "données" sont le message que vous essayez de faire passer et la "présentation" est la façon dont l'utilisateur voit cela.

J'utilise une seule ligne de résumé en haut et j'essaie de rester courte mais je ne me limite pas à un nombre arbitraire. Il serait bien mieux que Git fournisse un moyen de stocker les messages récapitulatifs en tant qu'entité distincte du message, mais comme il ne l'est pas, je dois en pirater un et utiliser le premier saut de ligne comme délimiteur (heureusement, de nombreux outils prennent en charge ce qui permet de séparer les données).

Pour le message lui-même, les nouvelles lignes indiquent quelque chose de significatif dans les données. Une seule nouvelle ligne indique un début / une pause dans une liste et une double nouvelle ligne indique une nouvelle pensée / idée.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

Voici à quoi cela ressemble dans une visionneuse qui enveloppe doucement le texte.

Il s'agit d'une ligne récapitulative, essayez de la garder courte et de terminer par un saut de ligne.

C'est une pensée, peut-être une explication de ce que j'ai fait dans un format lisible par l'homme. Il peut être complexe et long, composé de plusieurs phrases qui décrivent mon travail sous forme de dissertation. Ce n'est pas à moi de décider maintenant (au moment de l'auteur) comment l'utilisateur va consommer ces données.

Deux sauts de ligne séparent ces deux pensées. L'utilisateur peut lire ceci sur un téléphone ou un moniteur à écran large. Avez-vous déjà essayé de lire du texte enveloppé de 72 caractères sur un appareil qui n'affiche que 60 caractères? C'est une expérience vraiment douloureuse. En outre, la phrase d'ouverture de ce paragraphe (en supposant un format de style d'essai) devrait être une introduction au paragraphe, donc si un outil le choisit, il peut ne pas vouloir envelopper automatiquement et vous laisser juste voir le début de chaque paragraphe. Encore une fois, c'est à l'outil de présentation et non à moi (un auteur aléatoire à un moment de l'histoire) d'essayer de forcer ma mise en forme particulière dans la gorge de tous les autres.

À titre d'exemple, voici une liste de points:
* Point 1.
* Point 2.
* Point 3.

Je soupçonne que l'auteur de la recommandation de message de validation Git que vous avez lié n'a jamais écrit de logiciel qui sera consommé par un large éventail d'utilisateurs finaux sur différents appareils auparavant (c'est-à-dire un site Web) car à ce stade de l'évolution des logiciels / de l'informatique il est bien connu que le stockage de vos données avec des informations de présentation codées en dur est une mauvaise idée en ce qui concerne l'expérience utilisateur.

Je suis d'accord qu'il est intéressant de proposer un style de travail particulier. Cependant, à moins d'avoir la possibilité de définir le style, je suis généralement ce qui a été fait pour plus de cohérence.

Jetez un œil aux Commits du noyau Linux, le projet qui a lancé git si vous voulez, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , ils ne suivent pas la règle 50/72. La première ligne contient 54 caractères.

Je dirais que la cohérence est importante. Mettre en place des moyens appropriés pour identifier les utilisateurs qui ont effectué des validations (nom_utilisateur, email_utilisateur - en particulier sur les réseaux internes. User @ OFFICE-1-PC-10293982811111 n'est pas une adresse de contact utile). Selon le projet, rendez les détails appropriés disponibles dans la validation. Il est difficile de dire ce que cela devrait être; il peut s'agir de tâches terminées dans un processus de développement, puis de détails sur ce qui a changé.

Je ne crois pas que les utilisateurs devraient utiliser git dans un sens car certaines interfaces pour git traitent les commits de certaines manières.

Je dois également noter qu'il existe d'autres façons de trouver des commits. Pour commencer, git diffvous dira ce qui a changé. Vous pouvez également faire des choses comme git log --pretty=format:'%T %cN %ce'formater les options de git log.

La longueur de titre maximale recommandée est-elle vraiment de 50?

Je le crois depuis des années, mais comme je viens de le remarquer, la documentation de "git commit" indique en fait

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

On pourrait faire valoir que «moins de 50» ne peut signifier que «pas plus de 49».