Mario Pérez Esteso
Un mensaje de commit es una descripción corta de los cambios que has realizado en los archivos de un proyecto.
Escribir buenos mensajes de commit es muy importante tanto para las personas que trabajan contigo como para ti, ya que te servirán para saber exactamente qué ha pasado y qué cambios se han realizado en cada momento dentro de un proyecto.
Las buenas prácticas a la hora de programar y mantener código también aplican a cómo escribimos mensajes de commit, incluso siendo proyectos personales. Mi recomendación es que siempre utilices buenas prácticas incluso cuando sea un proyecto en el que solo tú estás participando.
Un mensaje de commit bien escrito es la mejor manera de proporcionar contexto sobre un cambio al resto de desarrolladores. Podríamos pensar que en el diferencial de código tenemos toda la información necesaria para saber qué ha cambiado pero, ¿cómo respondemos al porqué de dicho cambio? Ahí es donde entra en juego el mensaje en el commit.
Es muy común encontrarse commit escritos de mil maneras en un repositorio, sobre todo cuando hay más de una persona trabajando en él. Para solucionar esto, podemos utilizar una guía de estilo, igual que se hace en varios repositorios conocidos como por ejemplo el de Angular.js, que personalmente es el que yo utilizo.
Todos los mensajes de commit tienen tres partes: header, body y footer. Además, la cabecera tiene un formato especial que contiene 3 partes diferenciadas: type, scope y subject.
<type>(<scope>): <subject>
<Línea en blanco>
<body>
<Línea en blanco>
<footer>
Escribir un header es obligatorio en los commits, pero el scope es opcional.
Debe ser uno de los siguientes:
El scope se refiere a la parte del código en el que se está realizando un cambio, es decir, a qué clase o archivo afecta, si es para algún navegador específico, si es sobre una herramienta que se ha añadido, etc.
Esta es la parte que realmente describe lo que hemos cambiado dentro del scope. Debemos aplicar las siguientes reglas:
.) al final de la fraseAlgunos ejemplos de un subject bien escrito podrían ser:
update deployment documentationremove deprecated methodmerge pull request #312 from branch/namerelease version 1.2.3Algunos ejemplos de un subject mal escrito podrían ser:
refactored method to improve readability: no utiliza el imperativomore changes to class X: tampoco utiliza el imperativoI have released a new version.: no utiliza imperativo y tiene punto finalEl body sirve para explicar qué cambios hemos hecho y por qué los hemos hecho. No todos los commits son lo suficientemente complejos como para tener que escribir un body y a veces basta con escribir un buen header.
El footer también es opcional y suele utilizarse para añadir enlaces a algún issue tracker que estés utilizando como Jira, Redmine o Clubhouse.
Tanto si trabajamos solos en un proyecto como si trabajamos con un equipo, debemos tener siempre en mente que escribir buenos commits es muy importante para saber qué se ha hecho y por qué motivo. Tener una guía de estilo también viene muy bien y hará que el proyecto tenga una buena consistencia en cuanto a legibilidad e histórico de cambios.
