Escribe mejores mensajes de commit para ser feliz

A quién no le ha pasado tratar de buscar el commit donde se realizó un cambio o se solucionó un error y que se convierta en una auténtica odisea.

Una de las cosas que podemos mejorar bastante es escribir buenos mensajes de commit.

Vamos a ver algunas prácticas que si todos siguiéramos seríamos mucho más felices.

Introducción

Es bastante frecuente encontrarte mensajes de commit que te cuentan qué se ha cambiado y no de la mejor forma:

La principal utilidad de un mensaje de commit no es explicar qué hace el cambio, eso ya lo muestra el código, y puede ser visto en el historial.

Es mucho más útil explicar la razón que hay detrás de esos cambios.

Cada vez que realizamos un commit, estamos grabando una instantánea del proyecto. En el futuro podremos revertirla o compararla con otros commits.

Algo que reduce mucho el tiempo de búsqueda en el futuro, son las buenas descripciones en los commits, aparte de los commits atómicos.

¿Por qué debería escribir buenos mensajes de commit?

Normalmente vamos con prisas y pensamos que tenemos todo claro, pero ¿qué sucede cuando trabajas en varios proyectos y después de añadir cientos de commits en proyectos distintos o hayan pasado 12 meses o tengas que trabajar con las commits de otra persona?.

Dedica tiempo a escribir buenos mensajes en el presente, y tu yo del futuro u otra persona te lo agradecerá.

Los mensajes de commit se utilizan de muchas formas, entre ellas:

1. Para ayudar a un futuro lector a comprender rápidamente qué cambió y por qué cambió.
2. Para ayudar a deshacer fácilmente cambios específicos.
3. Para preparar notas de cambio o versiones mejoradas para un lanzamiento.

Estos tres casos de uso requieren un estilo de mensaje de confirmación limpio y coherente.

Recomendaciones para mensajes de commit

Los mensajes de commit no tienen por qué limitarse a una linea.

Podemos escribir varias lineas, separando con una linea en blanco cada parte para darle mayor legibilidad si es necesario.

Por defecto se ve la primera linea en herramientas como Github, pero se puede expandir para ver el resto.

Posibles partes en las que se puede dividir : título, cuerpo y pie.

El título es la única que sería obligatoria, el cuerpo y el pie pueden ser opcionales.

Título (obligatorio)

Debería comenzar con letra mayuscula, es decir, "Add password validation test" en lugar de "add password validation test".

No debe contener más de 50 caracteres. Esto es debido a que la mayoría de las herramientas donde se visualizan los mensajes de commit como Github tienen un ancho limitado.

Deberíamos usar el modo imperativo. Esta convención se alinea con los mensajes de confirmación generados por comandos como git merge y git revert.

Esto significa eliminar el tiempo verbal. No escribas un mensaje de commit que habla sobre lo que hiciste o estás haciendo.  

Fixed ... //bad

Fixing ... //bad

Fix ... //good

Sé que muchas veces estamos tentados de escribirlo en pasado “Added…”, “Fixed…” o “Removed…” pero cada commit hay que entenderlo como una instrucción para cambiar el estado del proyecto.

El cuerpo (opcional)

El cuerpo es interesante cuando los 50 caracteres del título se nos quedan cortos.

Podemos utilizar el cuerpo para complementar la información del título.

Podríamos explicar en qué consiste el cambio, pero sobretodo por qué es necesario.

Es recomendable que sea como máximo 100 caracteres.

Para tener mayor legibilidad deja un espacio en blanco separando el cuerpo y el título y para separar párrafos dentro del propio cuerpo.

Podemos utilizar guiones, bullet points o indentaciones si es es necesario.

El pie (opcional)

En las últimas líneas se pueden poner referencias a los ids de la tarea o tareas relacionadas.

En algunos proyectos he visto la referencia a la tarea en el título. Puede ser también buena idea, pero en caso de tener que indicar más de una tarea o tareas relacionadas, mejor en el pie.

El pie podemos añadir Breaking Changes si procede.

Breaking Changes deberían empezar con BREAKING CHANGE: con un espacio o salto de linea.

Uso de Prefijos

Para proyectos grandes, donde interviene un equipo de varias personas, es interesante acordar unas convenciones de prefijos que indican el tipo de commit.

<commit-type>[scope]: <description>

Por ejemplo:

feat(backend): add new code field to the user 
^--^  ^--------------------^
│     │
│     └--> # Description
│
└──------> # Type

En angular utilizan este tipo de convención en sus normas de mensajes de commit:

Estos serían los prefijos que usan:

• feat: Una nueva característica para el usuario.
• fix: Arregla un bug que afecta al usuario.
• perf: Cambios que mejoran el rendimiento del sitio.
• build: Cambios en el sistema de build, tareas de despliegue o instalación.
• ci: Cambios en la integración continua.
• docs: Cambios en la documentación.
• refactor: Refactorización del código como cambios de nombre de variables o funciones.
• style: Cambios de formato, tabulaciones, espacios o puntos y coma, etc; no afectan al usuario.
• test: Añade tests o refactoriza uno existente.

Ejemplo de un mensaje de commit

Fix: chart resize when it's rendered within a table

Reflow method of a chart is used to resize the chart according its container and it used with useRef works generally.

However there are some scenarios where does not work:

- When its parent is a table cell.
- It works when to resize the table making it bigger. 
- It doesn't work when to resize the table making it smaller. 

Hightchart issue: #1157

Conclusiones

Hemos visto algunas recomendaciones para escribir buenos mensajes de commit. Además hemos visto una serie de convecciones para prefijos que pueden ayudarnos cuando el proyecto es grande y hay varias personas.

Estas recomendaciones aparte de legibilidad, ayudan a realizar commits atómicos.