Cuando se contribuye al repositorio de un proyecto Git y se confirman los cambios (commit) se requiere un mensaje que explique las modificaciones introducidas en el código.

Estos mensajes son importantes porque:

• ayudan a entender los cambios sin tener que revisar el código;
• facilitan y normalizan la navegación a través del historial de Git; y
• filtran los cambios para facilitar la generación del archivo CHANGELOG.

Un artículo de Chris Beans (2014) evidenció esta importancia e introdujo siete reglas que debía tener un buen mensaje de commit que son la base de esta guía de buenas prácticas:

Plantilla para un mensaje de commit

Op asunto [ámbito]
«LÍNEA EN BLANCO»
Cuerpo
«LÍNEA EN BLANCO»
Pie

Por legibilidad, la primera línea de resumen no debería tener más de 50 caracteres, y el resto no más de 72. Visual Studio Code y otros entornos de desarrollo tienen en cuenta estos límites para facilitar la escritura de estos mensajes.

No olvidar que las líneas en blanco deben respetarse si se incluyen dos o los tres apartados de la plantilla.

Línea resumen: Op asunto [ámbito]

Donde:

• Op debe comenzar con letra mayúscula:
  • Añade (Add) – una nueva funcionalidad para los usuarios.
  • Modifica (Change) – alguna característica de una funcionalidad dada.
  • Elimina (Remove) – definitivamente una funcionalidad obsoleta.
  • Corrige (Fix) – un error que afecta al usuario.
  • Asegura (Security) – o mitiga una vulnerabilidad en el código.
    

    ---

  • Mejora (Improve) – el rendimiento o el uso de una funcionalidad existente.
  • Actualiza (Update) – sin añadir ni modificar funcionalidades, por ejemplo al refactorizar código, añadir documentación o incluir scripts de compilación y configuraciones.
  • Retoca (Tweak) – alguna particularidad del aspecto o una funcionalidad determinada.
    

    ---

  • Inicia (Initial) – para empezar el proyecto; por ejemplo Inicia el repositorio (Initial commit).
  • Integra (Merge) – la petición de fusión #123 de algúnusuario/algunarama.
  • Libera (Release) – la versión X.Y.Z del proyecto.
• asunto (subject) debe completar la frase imperativa del resumen y terminar sin punto.
• ámbito (scope) es opcional, omitiendo los corchetes si no se indica. Según el proyecto se pueden definir ámbitos como config, logging, common, framework, middleware, tests, database, lib, reporting, doc, browser, events, preprocessor, webserver, proxy, license, etc…

Hay que evitar las generalidades o los resúmenes fuera de contexto, teniendo en cuenta que si cuesta trabajo resumir quizás se están haciendo demasiados cambios a la vez.

Cuerpo

• El Cuerpo (Body) se omitirá si el resumen es suficiente para explicar el contenido y el contexto.
• Se pueden usar varias frases y crear listas con guiones o asteriscos. Las frases sí terminan con punto.
• Debe explicar el qué y el por qué, en lugar de el cómo; para que futuros colaboradores puedan saber las razones de haber escogido una solución frente a otras.

Pie

• El Pie (Footer) es opcional.
• Es útil para indicar las peticiones relacionadas que se han cerrado o se han visto afectadas (separadas por coma si son más de una).