Cuando aportamos al repositorio de un proyecto (commit), debemos seguir un mínimo de buenas prácticas para los mensajes que acompañan a ese commit.
Es un error común pensar que hay que limitarse a escribir una única línea que contenga toda la información.
La estructura ideal para el mensaje de un commit es la siguiente:
Título: Resumen breve de los cambios realizados(línea en blanco)Cuerpo (opcional): Explicación más detallada que aporta contexto e información adicional(línea en blanco)Pie (opcional): Menciones de los issues afectados
La utilidad del mensaje del commit no es explicar cuáles son los cambios que contiene ese commit, para eso podemos ver el código, la importancia del mensaje es explicar la razón que hay detrás de esos cambios.
El código fuente en el historial nos dice el cómo, los mensajes de commit nos dicen el por qué.
El título
El título del commit debe comenzar con una letra mayúscula y terminar sin punto. Trata de no usar más de 50 caracteres, no es necesario que te pongas a contar letras, es sólo una recomendación.
El título del commit debe estar en tiempo verbal imperativo, por ejemplo:
- Agrega el filtro de búsqueda para artículos
- Ubica el campo fecha al inicio de la factura
El cuerpo
Si el contenido y el contexto del commit se puede explicar en el título no es necesario incluir un cuerpo.
A diferencia del título, el cuerpo sí termina las frases con un punto, y podemos utilizar varias frases e incluso crear listas con guiones o asteriscos.
Usa el cuerpo del mensaje para explicar el qué y el por qué, no el cómo.
Se trata de explicar el problema que el commit resuelve, el código en sí ya explica el cómo.
El pie
Se considera el pie a las últimas líneas del cuerpo del commit, en el pie se pueden colocar referencias a los IDs de los issues afectados o relacionados.
Plantilla de un mensaje de commit
Resumen de los cambios en 50 caracteres o menos
Texto explicativo más detallado, solo si es necesario. La línea en blanco que separa el título del resto del texto es crucial (a no ser que omitas el cuerpo y el mensaje solo tenga título); algunas herramientas pueden mostrar información alterada si omites la línea en blanco de separación.
También se pueden añadir más párrafos, separados igualmente por una línea en blanco.
- Se pueden añadir listas
- Para las listas se usan guiones o asteriscos (como en Markdown)
En el pie, se pueden poner referencias a los IDs de los issue trackers, por ejemplo:
Resuelve: #193
Afecta a: #270, #286
Sabremos que lo estamos haciendo bien si el hilo de mensajes del historial de nuestro proyecto tiene coherencia y consistencia.
Si quieres aprender más sobre git te recomiendo el Curso Git Desde Cero de EDteam.
Eso es todo por ahora gente del futuro, nos leemos en el siguiente artículo.