Messages de commit Git : Formatage 50/72

Question

Tim Pope plaide en faveur d'un style particulier de message de commit Git dans son billet de blog : http://www.tpope.net/node/106 .

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

• La première ligne ne doit pas dépasser 50 caractères.
• Puis une ligne blanche.
• Le reste du texte doit être enveloppé à 72 caractères.

Son billet de blog donne la raison d'être de ces recommandations (que j'appellerai "formatage 50/72" par souci de concision) :

• Dans la pratique, certains outils traitent la première ligne comme un objet et le deuxième paragraphe comme un corps (comme pour un courriel).
• git log ne gère pas l'habillage, il est donc difficile à lire si les lignes sont trop longues.
• git format-patch --stdout convertit les commits en email - pour être agréable, il est utile que vos commits soient déjà bien enveloppés.

J'aimerais ajouter un point avec lequel je pense que Tim serait d'accord :

• L'acte de résumer votre livraison est une bonne pratique inhérente à tout système de contrôle de version. Cela permet aux autres (ou à vous plus tard) de trouver plus rapidement les commits pertinents.

Donc, j'ai plusieurs angles à ma question :

• Quelle proportion (approximativement) des "leaders d'opinion" ou des "utilisateurs expérimentés" de Git adopte 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 de la communauté.
• Pour ceux qui n'utilisent pas ce formatage, y a-t-il une raison de principe pour utiliser un style de formatage différent ? (Veuillez noter que je cherche un argument sur le fond, pas un "je n'en ai jamais entendu parler" ou "je m'en fiche").
• Empiriquement parlant, quel pourcentage de dépôts Git adopte ce style ? (Au cas où quelqu'un voudrait faire une analyse sur les dépôts GitHub indice, indice).

Mon propos n'est pas de recommander le style 50/72 ou de dénigrer les autres styles. (Pour être franc, je préfère ce style, mais je suis ouvert à d'autres idées.) Je veux simplement connaître les raisons pour lesquelles les gens aiment ou s'opposent aux différents styles de messages de Git commit. (N'hésitez pas à soulever des points qui n'ont pas été mentionnés, aussi).

Answer 1

En ce qui concerne la ligne "summary" (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 mainteneurs 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 commits qui ont des lignes de résumé qui sont plus longues (certaines beaucoup plus longues) que ce que cette parcelle 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 basé sur le texte :

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

Answer 2

En ce qui concerne les "leaders d'opinion" : Linus plaide avec insistance en faveur d'une mise en ligne du message de livraison complet :

[ ] nous utilisons des colonnes de 72 caractères pour l'habillage des mots, sauf pour les citations qui ont un format de ligne spécifique.

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

Answer 3

La séparation de la présentation et des données est le moteur de mes messages d'engagement ici.

Votre message de livraison ne devrait pas être enveloppé dans un emballage rigide à l'adresse suivante cualquier Le nombre de caractères et les sauts de ligne doivent être utilisés pour séparer les pensées, les paragraphes, etc. qui font partie 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 le voit.

J'utilise une seule ligne de résumé en haut et j'essaie de la garder courte mais je ne me limite pas à un nombre arbitraire. Ce serait bien mieux si Git fournissait un moyen de stocker les messages de résumé comme une entité séparée du message, mais comme ce n'est pas le cas, je dois en créer un et j'utilise le premier saut de ligne comme délimiteur (heureusement, de nombreux outils supportent ce moyen de séparer les données).

Pour le message lui-même, les nouvelles lignes indiquent quelque chose de significatif dans les données. Un simple saut de ligne indique un début/une fin de liste et un double saut de 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 le texte de manière souple.

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

Ceci 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 d'essai. Ce n'est pas à moi de décider maintenant (au moment de la rédaction) comment l'utilisateur va consommer ces données.

Deux retours à la ligne séparent ces deux pensées. L'utilisateur peut lire ce texte sur un téléphone ou un écran large. Avez-vous déjà essayé de lire un texte de 72 caractères sur un appareil qui n'en affiche que 60 ? C'est une expérience vraiment pénible. De plus, la phrase d'ouverture de ce paragraphe (dans le cas d'un format de style rédactionnel) doit servir d'introduction au paragraphe. Par conséquent, si un outil le souhaite, il peut ne pas procéder à une mise en forme automatique et ne laisser apparaître que le début de chaque paragraphe. Encore une fois, c'est à l'outil de présentation de décider et non à moi (un auteur aléatoire à un moment donné de l'histoire) d'essayer d'imposer mon formatage particulier à tous les autres.

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

Je soupçonne que l'auteur du message de recommandation de 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 (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 pour l'expérience utilisateur.

Answer 4

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

Je jette un coup d'œ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 du 50/72. La première ligne compte 54 caractères.

Je dirais que la cohérence est importante. Mettez en place des moyens appropriés pour identifier les utilisateurs qui ont fait des commits (user.name, user.email - surtout sur les réseaux internes. User@OFFICE-1-PC-10293982811111 n'est pas une adresse de contact utile). Selon le projet, mettez les détails appropriés à disposition dans le commit. Il est difficile de dire ce que cela devrait être ; cela pourrait être les tâches accomplies dans un processus de développement, puis les détails de ce qui a été changé.

Je ne crois pas que les utilisateurs doivent utiliser git d'une seule façon parce que certaines interfaces de git traitent les commits de certaines manières.

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

Answer 5

Le formatage 50/72 semble intéressant. Lorsque l'on travaille avec des équipes de développeurs, c'est une bonne pratique d'établir des indicateurs communs entre eux, comme les modèles de conception. Les arguments que Tim Pope nous donne sont logiques. Je pense que la seule raison d'utiliser un style de formatage différent peut être les meilleures pratiques imposées par les managers ou l'entreprise.