Git commit trailers: què són i com es fan servir

Per què importen els commit trailers

La majoria de desenvolupadors pensen en un missatge de commit com en dues parts: un títol curt i, opcionalment, un cos més llarg. És cert, però sovint hi ha una tercera part al final que és fàcil de passar per alt: els commit trailers.

Els trailers són línies estructurades que s’afegeixen al final d’un missatge de commit. Semblen senzills, però poden contenir metadades útils en un format que entenen tant les persones com les eines.

Segurament n’has vist exemples com aquests:

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

Aquestes línies no són convencions a l’atzar. Git té suport integrat per analitzar-les i editar-les, i el projecte Git documenta les convencions més habituals a les seves pautes per enviar pedaços.

Què són els commit trailers

Un trailer és un parell clau-valor situat al final d’un missatge de commit, normalment després d’una línia en blanc. A la pràctica, funcionen com un peu de pàgina per a les metadades del commit.

Aquí tens un exemple senzill:

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’assumpte explica el canvi. El cos aporta context. Els trailers descriuen informació addicional sobre com s’ha fet, revisat o validat el canvi.

Aquesta estructura és especialment útil quan vols que l’historial de commits sigui alhora llegible i processable per una màquina.

Els trailers més habituals

Aquests són alguns dels trailers que veuràs més sovint en projectes de codi obert i fluxos de treball col·laboratius.

Signed-off-by

Aquest trailer s’utilitza habitualment per indicar que l’autor accepta un procés de contribució, sovint el Developer Certificate of Origin.

Exemple:

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

Els projectes que demanen als col·laboradors que certifiquin que tenen dret a enviar el codi sovint exigeixen aquest trailer a cada commit.

Reviewed-by

Aquest trailer registra qui ha revisat el canvi.

Exemple:

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

És útil en equips o projectes on la revisió és una part important del procés de desenvolupament i vols que aquesta informació quedi lligada al mateix commit.

Acked-by

Aquest trailer indica que algú ha mirat el canvi i hi està d’acord, encara que no en fos el revisor principal.

Exemple:

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

És habitual en fluxos de codi obert on diversos mantenidors o experts d’una àrea volen mostrar el seu suport a un pedaç.

Tested-by

Aquest trailer registra qui ha provat el canvi.

Exemple:

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

És útil quan les proves les fa algú que no és l’autor, sobretot en correccions d’errors, comprovacions en plataformes concretes o validacions d’una versió.

Reported-by

Aquest trailer reconeix la persona que va informar del problema que ha donat lloc al pedaç.

Exemple:

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

Ajuda a mantenir la traçabilitat i dona el mèrit a qui va detectar l’error o el problema.

Suggested-by

Aquest trailer reconeix la persona que va suggerir l’enfocament o la idea del pedaç.

Exemple:

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

És útil quan algú ha marcat la direcció de la correcció o la funcionalitat, encara que no hagi implementat el canvi personalment.

Helped-by

Aquest trailer s’utilitza sovint per reconèixer algú que ha aportat orientació útil o ajuda en la depuració sense ser-ne coautor.

Exemple:

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

És útil quan algú dona una ajuda significativa, però no prou per justificar l’autoria del commit.

Co-authored-by

Aquest trailer reconeix un altre col·laborador del mateix commit.

Exemple:

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

És útil per a la programació en parella, la programació en grup o qualsevol canvi en què hagi contribuït de manera significativa més d’una persona.

On-behalf-of

Aquest trailer és menys universal, però val la pena conèixer-lo perquè GitHub el documenta per als commits creats en nom d’una organització.

Exemple:

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

Si fas un commit com a representant d’una organització, aquest trailer pot expressar aquesta relació al missatge de commit. GitHub ho explica a la seva guia sobre com crear un commit en nom d’una organització.

Convencions

Els trailers són senzills, però no són del tot lliures. Git els admet mitjançant git interpret-trailers, i el projecte Git documenta les convencions més esteses a Submitting Patches: commit trailers.

A la pràctica, això normalment vol dir que:

• Els trailers apareixen al final del missatge de commit
• Cada trailer és un parell token: valor
• El bloc de trailers normalment està separat del cos per una línia en blanc
• Els equips sovint reutilitzen noms convencionals com Signed-off-by, Reviewed-by o Acked-by

Pots inventar-te els teus propis noms de trailers, però les convencions establertes solen ser millor opció quan vols que altres desenvolupadors i eines els entenguin de seguida.

Com fan servir Git i GitHub els commit trailers

Un detall útil que molts desenvolupadors no coneixen és que el mateix Git entén els trailers. No és només una convenció afegida per les plataformes d’allotjament.

Git els admet amb ordres com:

git interpret-trailers

Això vol dir que els trailers es poden analitzar, afegir i normalitzar de manera estructurada en lloc de tractar-los com a text qualsevol. Si vols automatitzar la gestió dels commit trailers, és el primer lloc on mirar.

GitHub també fa servir alguns trailers de manera específica. Els exemples més clars són Co-authored-by, que GitHub reconeix per atribuir la coautoria a la seva guia sobre com crear un commit amb diversos autors, i On-behalf-of, que GitHub documenta per als commits fets en nom d’una organització a la guia sobre com crear un commit en nom d’una organització. I no és només una qüestió estètica: GitHub diu que els commits amb coautors són visibles a GitHub, es poden incloure a les contribucions del perfil i a les estadístiques d’un repositori, i el gràfic de col·laboradors pot incloure els coautors dels commits. Per tant, un trailer Co-authored-by ben formatat pot afectar la secció de col·laboradors i les vistes de contribucions d’un repositori, no només la pàgina del commit.

Per això vaig crear coauthorcheck, un validador lleuger per als trailers Co-authored-by per fer servir a la CLI, als hooks de pre-commit i a les GitHub Actions.

Les altres plataformes d’allotjament de Git normalment conserven els trailers perquè formen part del missatge de commit, però la manera de mostrar-los i el suport per automatitzar-los varien d’una plataforma a una altra. És un motiu més per preferir, sempre que es pugui, noms de trailers àmpliament reconeguts.

Conclusió

Els trailers són una part petita d’un missatge de commit, però marquen una diferència real. Permeten als equips afegir informació estructurada als commits d’una manera que continua sent llegible per a les persones i útil per a les eines.

Quan comences a fixar-t’hi, t’adones que resolen diversos problemes pràctics alhora: atribució, traçabilitat de les revisions, historial de proves, normes de contribució i automatització. És una d’aquelles funcionalitats de Git que al principi semblen menors, però que guanyen valor a mesura que la col·laboració creix.