Git commit trailers: cosa sono e come si usano

Perché i commit trailers sono importanti

La maggior parte degli sviluppatori pensa a un messaggio di commit come a due parti: un titolo breve e, facoltativamente, un corpo più lungo. È vero, ma spesso c’è una terza parte alla fine che passa facilmente inosservata: i commit trailers.

I trailer sono righe strutturate aggiunte in fondo a un messaggio di commit. Sembrano semplici, ma possono contenere metadati utili in un formato comprensibile sia per le persone sia per gli strumenti.

Probabilmente ne hai già visti alcuni, come questi:

Signed-off-by: Sheldon Cooper <sheldon@example.com>
Reviewed-by: Leonard Hofstader <leonard@example.com>
Tested-by: Howard Wolowitz <howard@example.com>

Queste righe non sono convenzioni a caso. Git ha un supporto integrato per analizzarle e modificarle, e il progetto Git documenta le convenzioni più comuni nelle sue linee guida per l’invio di patch.

Cosa sono i commit trailers

Un trailer è una coppia chiave-valore posta alla fine di un messaggio di commit, di solito dopo una riga vuota. In pratica, funzionano come un piè di pagina per i metadati del commit.

Ecco un esempio semplice:

Improve validation for API tokens

Reject empty values earlier and return a clearer error message.

Reviewed-by: Berndaette Rostenkowski <bernadette@example.com>
Tested-by: Amy Farrah Fowler <amy@example.com>

L’oggetto spiega la modifica. Il corpo dà il contesto. I trailer aggiungono informazioni su come la modifica è stata prodotta, revisionata o validata.

Questa struttura è particolarmente utile quando vuoi che la cronologia dei commit sia allo stesso tempo leggibile ed elaborabile da una macchina.

I trailer più comuni

Ecco alcuni dei trailer che vedrai più spesso nei progetti open source e nei flussi di lavoro collaborativi.

Signed-off-by

Questo trailer si usa di solito per indicare che l’autore accetta un processo di contribuzione, spesso il Developer Certificate of Origin.

Esempio:

Signed-off-by: Simone Gigante <simone@example.com>

I progetti che chiedono ai contributori di certificare di avere il diritto di inviare il codice spesso richiedono questo trailer in ogni commit.

Reviewed-by

Questo trailer registra chi ha revisionato la modifica.

Esempio:

Reviewed-by: Raj Koothrappali <raj@example.com>

È utile in team o progetti in cui la revisione è una parte importante del processo di sviluppo e vuoi che questa informazione resti legata al commit stesso.

Acked-by

Questo trailer indica che qualcuno ha dato un’occhiata alla modifica ed è d’accordo, anche se non era il revisore principale.

Esempio:

Acked-by: Leslie Winkle <lesie@example.com>

È comune nei flussi open source in cui più maintainer o esperti di un’area vogliono segnalare il loro appoggio a una patch.

Tested-by

Questo trailer registra chi ha testato la modifica.

Esempio:

Tested-by: Barry Kripke <barry@example.com>

È utile quando i test li fa qualcuno diverso dall’autore, soprattutto per correzioni di bug, verifiche su piattaforme specifiche o validazioni di una release.

Reported-by

Questo trailer dà credito alla persona che ha segnalato il problema da cui è nata la patch.

Esempio:

Reported-by: Arthur Jeffries <arthur@example.com>

Aiuta a mantenere la tracciabilità e riconosce il merito di chi ha individuato il bug o il problema.

Suggested-by

Questo trailer dà credito alla persona che ha suggerito l’approccio o l’idea alla base della patch.

Esempio:

Suggested-by: Wil Wheaton <wil@example.com>

È utile quando qualcuno ha indicato la direzione della correzione o della funzionalità, anche se non ha implementato la modifica in prima persona.

Helped-by

Questo trailer si usa spesso per riconoscere qualcuno che ha dato indicazioni utili o una mano nel debug senza essere coautore.

Esempio:

Helped-by: Bert Kibbler <bert@example.com>

È utile quando qualcuno dà un aiuto concreto, ma non abbastanza da giustificare la paternità del commit.

Co-authored-by

Questo trailer riconosce un altro contributore dello stesso commit.

Esempio:

Co-authored-by: Sheldon Cooper <sheldon@example.com>

È utile per il pair programming, il mob programming o qualsiasi modifica a cui più persone abbiano contribuito in modo significativo.

On-behalf-of

Questo trailer è meno diffuso, ma vale la pena conoscerlo perché GitHub lo documenta per i commit creati per conto di un’organizzazione.

Esempio:

On-behalf-of: Example Org <opensource@example.org>

Se fai un commit come rappresentante di un’organizzazione, questo trailer può esprimere quel legame nel messaggio di commit. GitHub lo spiega nella sua guida su come creare un commit per conto di un’organizzazione.

Convenzioni

I trailer sono semplici, ma non del tutto liberi. Git li supporta tramite git interpret-trailers, e il progetto Git documenta le convenzioni più diffuse in Submitting Patches: commit trailers.

In pratica, di solito significa che:

• I trailer compaiono alla fine del messaggio di commit
• Ogni trailer è una coppia token: valore
• Il blocco dei trailer è di solito separato dal corpo da una riga vuota
• I team riusano spesso nomi convenzionali come Signed-off-by, Reviewed-by o Acked-by

Puoi inventare i tuoi nomi di trailer, ma le convenzioni consolidate sono di solito la scelta migliore quando vuoi che altri sviluppatori e strumenti li capiscano subito.

Come Git e GitHub usano i commit trailers

Un dettaglio utile che sfugge a molti sviluppatori è che Git stesso capisce i trailer. Non è solo una convenzione aggiunta sopra dalle piattaforme di hosting.

Git li supporta con comandi come:

git interpret-trailers

Questo significa che i trailer possono essere analizzati, aggiunti e normalizzati in modo strutturato invece di essere trattati come testo qualsiasi. Se vuoi automatizzare la gestione dei commit trailers, è il primo posto da cui partire.

Anche GitHub usa alcuni trailer in modo specifico. Gli esempi più chiari sono Co-authored-by, che GitHub riconosce per attribuire la coautoria nella sua guida su come creare un commit con più autori, e On-behalf-of, che GitHub documenta per i commit fatti a nome di un’organizzazione nella guida su come creare un commit per conto di un’organizzazione. E non è solo una questione estetica: GitHub dice che i commit con coautori sono visibili su GitHub, possono essere inclusi nei contributi del profilo e nelle statistiche di un repository, e il grafico dei contributori può includere i coautori dei commit. Quindi un trailer Co-authored-by formattato correttamente può influire sulla sezione dei contributori e sulle relative viste dei contributi di un repository, non solo sulla pagina del commit.

Per questo ho creato coauthorcheck, un validatore leggero per i trailer Co-authored-by da usare nella CLI, negli hook di pre-commit e nelle GitHub Actions.

Le altre piattaforme di hosting Git di solito conservano i trailer perché fanno parte del messaggio di commit, ma il modo in cui li mostrano e il supporto all’automazione cambiano da piattaforma a piattaforma. Un motivo in più per preferire, quando possibile, nomi di trailer ampiamente riconosciuti.

Conclusione

I trailer sono una piccola parte di un messaggio di commit, ma fanno una vera differenza. Permettono ai team di associare informazioni strutturate ai commit in un modo che resta leggibile per le persone e utile per gli strumenti.

Quando inizi a notarli, ti accorgi che risolvono diversi problemi pratici in un colpo solo: attribuzione, tracciabilità delle revisioni, storico dei test, regole di contribuzione e automazione. Sono una di quelle funzionalità di Git che all’inizio sembrano marginali, ma diventano sempre più preziose man mano che la collaborazione cresce.