Git commit trailers: qué son y cómo se usan

Por qué importan los commit trailers

La mayoría de desarrolladores piensan en un mensaje de commit como dos partes: un título corto y, opcionalmente, un cuerpo más largo. Es cierto, pero a menudo hay una tercera parte al final que es fácil pasar por alto: los commit trailers.

Los trailers son líneas estructuradas que se añaden al final de un mensaje de commit. Parecen sencillos, pero pueden contener metadatos útiles en un formato que entienden tanto las personas como las herramientas.

Seguramente has visto ejemplos como estos:

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

Estas líneas no son convenciones al azar. Git tiene soporte integrado para analizarlas y editarlas, y el proyecto Git documenta las convenciones más habituales en sus pautas para enviar parches.

Qué son los commit trailers

Un trailer es un par clave-valor situado al final de un mensaje de commit, normalmente después de una línea en blanco. En la práctica, funcionan como un pie de página para los metadatos del commit.

Aquí tienes un ejemplo sencillo:

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>

El asunto explica el cambio. El cuerpo aporta contexto. Los trailers describen información adicional sobre cómo se hizo, revisó o validó el cambio.

Esta estructura es especialmente útil cuando quieres que el historial de commits sea a la vez legible y procesable por una máquina.

Los trailers más habituales

Estos son algunos de los trailers que verás más a menudo en proyectos de código abierto y flujos de trabajo colaborativos.

Signed-off-by

Este trailer se usa habitualmente para indicar que el autor acepta un proceso de contribución, a menudo el Developer Certificate of Origin.

Ejemplo:

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

Los proyectos que piden a los colaboradores que certifiquen que tienen derecho a enviar el código suelen exigir este trailer en cada commit.

Reviewed-by

Este trailer registra quién ha revisado el cambio.

Ejemplo:

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

Es útil en equipos o proyectos donde la revisión es una parte importante del proceso de desarrollo y quieres que esa información quede ligada al propio commit.

Acked-by

Este trailer indica que alguien ha mirado el cambio y está de acuerdo, aunque no fuera el revisor principal.

Ejemplo:

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

Es habitual en flujos de código abierto donde varios mantenedores o expertos de un área quieren mostrar su apoyo a un parche.

Tested-by

Este trailer registra quién ha probado el cambio.

Ejemplo:

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

Es útil cuando las pruebas las hace alguien distinto del autor, sobre todo en correcciones de errores, comprobaciones en plataformas concretas o validaciones de una versión.

Reported-by

Este trailer reconoce a la persona que informó del problema que dio lugar al parche.

Ejemplo:

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

Ayuda a mantener la trazabilidad y da el mérito a quien detectó el error o el problema.

Suggested-by

Este trailer reconoce a la persona que sugirió el enfoque o la idea detrás del parche.

Ejemplo:

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

Es útil cuando alguien marcó la dirección de la corrección o la funcionalidad, aunque no implementara el cambio personalmente.

Helped-by

Este trailer se usa a menudo para reconocer a alguien que aportó orientación útil o ayuda en la depuración sin ser coautor.

Ejemplo:

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

Es útil cuando alguien presta una ayuda significativa, pero no suficiente para justificar la autoría del commit.

Co-authored-by

Este trailer reconoce a otro colaborador del mismo commit.

Ejemplo:

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

Es útil para la programación en pareja, la programación en grupo o cualquier cambio en el que haya contribuido de forma significativa más de una persona.

On-behalf-of

Este trailer es menos universal, pero vale la pena conocerlo porque GitHub lo documenta para los commits creados en nombre de una organización.

Ejemplo:

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

Si haces un commit como representante de una organización, este trailer puede expresar esa relación en el mensaje de commit. GitHub lo explica en su guía sobre cómo crear un commit en nombre de una organización.

Convenciones

Los trailers son sencillos, pero no son del todo libres. Git los admite mediante git interpret-trailers, y el proyecto Git documenta las convenciones más extendidas en Submitting Patches: commit trailers.

En la práctica, eso normalmente significa que:

• Los trailers aparecen al final del mensaje de commit
• Cada trailer es un par token: valor
• El bloque de trailers suele estar separado del cuerpo por una línea en blanco
• Los equipos suelen reutilizar nombres convencionales como Signed-off-by, Reviewed-by o Acked-by

Puedes inventarte tus propios nombres de trailers, pero las convenciones establecidas suelen ser mejor opción cuando quieres que otros desarrolladores y herramientas los entiendan de inmediato.

Cómo usan Git y GitHub los commit trailers

Un detalle útil que muchos desarrolladores pasan por alto es que el propio Git entiende los trailers. No es solo una convención añadida por las plataformas de alojamiento.

Git los admite con comandos como:

git interpret-trailers

Eso significa que los trailers se pueden analizar, añadir y normalizar de forma estructurada en lugar de tratarlos como texto cualquiera. Si quieres automatizar la gestión de los commit trailers, es el primer sitio donde mirar.

GitHub también usa algunos trailers de forma específica. Los ejemplos más claros son Co-authored-by, que GitHub reconoce para atribuir la coautoría en su guía sobre cómo crear un commit con varios autores, y On-behalf-of, que GitHub documenta para los commits hechos en nombre de una organización en la guía sobre cómo crear un commit en nombre de una organización. Y no es solo una cuestión estética: GitHub dice que los commits con coautores son visibles en GitHub, pueden incluirse en las contribuciones del perfil y en las estadísticas de un repositorio, y el gráfico de colaboradores puede incluir a los coautores de los commits. Por tanto, un trailer Co-authored-by bien formateado puede afectar a la sección de colaboradores y a las vistas de contribuciones de un repositorio, no solo a la página del commit.

Por eso creé coauthorcheck, un validador ligero para los trailers Co-authored-by que se puede usar en la CLI, en hooks de pre-commit y en GitHub Actions.

Las demás plataformas de alojamiento de Git suelen conservar los trailers porque forman parte del mensaje de commit, pero la forma de mostrarlos y el soporte para automatizarlos varían de una plataforma a otra. Es un motivo más para preferir, siempre que se pueda, nombres de trailers ampliamente reconocidos.

Conclusión

Los trailers son una parte pequeña de un mensaje de commit, pero marcan una diferencia real. Permiten a los equipos añadir información estructurada a los commits de una forma que sigue siendo legible para las personas y útil para las herramientas.

Cuando empiezas a fijarte en ellos, te das cuenta de que resuelven varios problemas prácticos a la vez: atribución, trazabilidad de las revisiones, historial de pruebas, normas de contribución y automatización. Son una de esas funcionalidades de Git que al principio parecen menores, pero que ganan valor a medida que la colaboración crece.