Messaggi Git Commit: formattazione 50/72

Tim Pope sostiene un particolare stile di messaggio di commit Git nel suo post sul blog: http://www.tpope.net/node/106 .

Ecco un breve riassunto di ciò che raccomanda:

• La prima riga è di 50 caratteri o meno.
• Quindi una riga vuota.
• Il testo rimanente deve essere composto da 72 caratteri.

Il suo post sul blog fornisce la logica di questi consigli (che chiamerò "formattazione 50/72" per brevità):

• In pratica, alcuni strumenti trattano la prima riga come riga dell'oggetto e il secondo paragrafo come un corpo (simile all'email).
• git log non gestisce il wrapping, quindi è difficile leggere se le righe sono troppo lunghe.
• git format-patch --stdout converte i commit in e-mail - quindi per giocare bene aiuta se i tuoi commit sono già ben inseriti.

Un punto che vorrei aggiungere e che penso che Tim sarebbe d'accordo:

• L'atto di riassumere il commit è una buona pratica intrinsecamente in qualsiasi sistema di controllo della versione. Aiuta gli altri (o più tardi) a trovare gli commit pertinenti più rapidamente.

Quindi, ho un paio di angolazioni alla mia domanda:

• Quale pezzo (approssimativamente) di "leader di pensiero" o "utenti esperti" di Git abbraccia lo stile di formattazione 50/72? Lo chiedo perché a volte i nuovi utenti non conoscono o non si preoccupano delle pratiche della comunità.
• Per coloro che non usano questa formattazione, c'è un motivo di principio per usare uno stile di formattazione diverso? (Nota che sto cercando una discussione sul merito, non "Non ne ho mai sentito parlare" o "Non mi interessa".)
• Empiricamente parlando, quale percentuale di repository Git abbraccia questo stile? (Nel caso qualcuno volesse fare un'analisi sui repository GitHub ... suggerimento, suggerimento.)

Il mio punto qui non è di raccomandare lo stile 50/72 o abbattere altri stili. (Per essere aperto a riguardo, lo preferisco, ma sono aperto ad altre idee.) Voglio solo ottenere la logica del perché alle persone piacciono o si oppongono a vari stili di messaggi di Git. (Sentiti libero di evidenziare anche punti che non sono stati menzionati.)

Per quanto riguarda la linea di "riepilogo" (i 50 nella tua formula), la documentazione del kernel Linux ha questo da 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.

Detto questo, sembra che i manutentori del kernel provino davvero a mantenere le cose intorno ai 50. Ecco un istogramma delle lunghezze delle righe di riepilogo nel log git per il kernel:

( visualizza a schermo intero )

Vi è una manciata di commit con righe di riepilogo più lunghe (alcune molto più lunghe) di quelle che questa trama può contenere senza far sembrare la parte interessante come una singola riga. (Probabilmente c'è qualche tecnica statistica elaborata per incorporare questi dati qui ma vabbè ... :-)

Se vuoi vedere le lunghezze grezze:

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

o un istogramma basato su testo:

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

Per quanto riguarda i "leader del pensiero": Linus sostiene con enfasi il ritorno a capo automatico per l'intero messaggio di commit:

[…] Usiamo colonne di 72 caratteri per il ritorno a capo automatico, ad eccezione del materiale citato che ha uno specifico formato di linea.

Le eccezioni si riferiscono principalmente al testo "non in prosa", ovvero al testo che non è stato digitato da un essere umano per il commit, ad esempio i messaggi di errore del compilatore.

La separazione di presentazione e dati guida i miei messaggi di commit qui.

Il tuo messaggio di commit non dovrebbe essere complicato in nessun conteggio dei caratteri e invece le interruzioni di riga dovrebbero essere utilizzate per separare pensieri, paragrafi, ecc. Come parte dei dati, non della presentazione. In questo caso, i "dati" sono il messaggio che si sta tentando di trasmettere e la "presentazione" è il modo in cui l'utente lo vede.

Uso una singola riga di riepilogo in alto e cerco di mantenerla breve ma non mi limito a un numero arbitrario. Sarebbe molto meglio se Git fornisse effettivamente un modo per archiviare i messaggi di riepilogo come entità separata dal messaggio, ma dal momento che non devo hackerarne uno e uso la prima riga come delimitatore (fortunatamente, molti strumenti supportano questo significa suddividere i dati).

Per il messaggio stesso, le nuove righe indicano qualcosa di significativo nei dati. Una nuova riga indica un inizio / interruzione in un elenco e una doppia riga indica un nuovo pensiero / idea.

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.

Ecco come appare in un visualizzatore che avvolge delicatamente il testo.

Questa è una riga di riepilogo, cerca di mantenerla breve e termina con un'interruzione di riga.

Questo è un pensiero, forse una spiegazione di ciò che ho fatto in un formato leggibile dall'uomo. Può essere complesso e lungo composto da diverse frasi che descrivono il mio lavoro in formato saggio. Non spetta a me decidere ora (al momento dell'autore) come l'utente utilizzerà questi dati.

Due interruzioni di riga separano questi due pensieri. L'utente potrebbe leggerlo su un telefono o su un monitor a schermo largo. Hai mai provato a leggere il testo racchiuso tra 72 caratteri su un dispositivo che visualizza solo 60 caratteri? È un'esperienza davvero dolorosa. Inoltre, la frase di apertura di questo paragrafo (assumendo il formato dello stile del saggio) dovrebbe essere un'introduzione al paragrafo, quindi se uno strumento lo sceglie potrebbe non voler avvolgere automaticamente e farti vedere l'inizio di ogni paragrafo. Ancora una volta, spetta allo strumento di presentazione non io (un autore casuale a un certo punto della storia) provare a forzare la mia particolare formattazione nella gola di tutti gli altri.

Proprio come un esempio, ecco un elenco di punti:
* Punto 1.
* Punto 2.
* Punto 3.

Il mio sospetto è che l'autore della raccomandazione del messaggio di commit di Git che hai collegato non abbia mai scritto software che verrà consumato da una vasta gamma di utenti finali su diversi dispositivi prima (cioè un sito Web) da allora a questo punto nell'evoluzione del software / informatica è noto che la memorizzazione dei dati con informazioni di presentazione codificate è una cattiva idea per quanto riguarda l'esperienza dell'utente.

Concordo sul fatto che sia interessante proporre un particolare stile di lavoro. Tuttavia, a meno che non abbia la possibilità di impostare lo stile, di solito seguo ciò che è stato fatto per coerenza.

Dando un'occhiata a Linux Kernel Commits, il progetto che ha avviato git se vuoi, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , non seguono la regola 50/72. La prima riga è di 54 caratteri.

Direi che la coerenza conta. Impostare mezzi adeguati per identificare gli utenti che hanno effettuato i commit (nome utente, nome utente e-mail, in particolare sulle reti interne. L'utente @ OFFICE-1-PC-10293982811111 non è un indirizzo di contatto utile). A seconda del progetto, rendere disponibili i dettagli appropriati nel commit. È difficile dire cosa dovrebbe essere; potrebbero essere attività completate in un processo di sviluppo, quindi dettagli di ciò che è cambiato.

Non credo che gli utenti dovrebbero usare git in un modo perché alcune interfacce per git trattano i commit in determinati modi.

Devo anche notare che ci sono altri modi per trovare commit. Per cominciare, git diffti dirò cosa è cambiato. Puoi anche fare cose come git log --pretty=format:'%T %cN %ce'formattare le opzioni di git log.

La lunghezza massima consigliata per il titolo è davvero 50?

Ci ho creduto per anni, ma come ho appena notato la documentazione di "git commit" in realtà afferma

$ 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

Si potrebbe sostenere che "meno di 50" può significare solo "non più di 49".