Commit: No cometas este error

La importancia de un buen commit

Codeicus

Published in

Codeicus

5 min readMay 3, 2023

No te pasó desarrollando que te encontraste con mensajes como:

“cambios varios”
“fix-bug”
“más cambios”
“Cambios para ticket 329–330–331”
“no tengo idea que estoy escribiendo”

Sé que seguramente sí 😅, a todos nos pasó alguna vez, y si tenemos que volver atrás en la historia la verdad no es agradable encontrarse con estos mensajes.

Escribir un buen mensaje en el commit es de suma importancia tanto para el proyecto, como para el cliente y hasta para la empresa 🤯. Sí, así de importante es!.

¿Por qué es importante escribir un buen mensaje de commit?

Veámoslo con un ejemplo (caso real 🤓)

Es probable que en el día a día trabajando en un proyecto que está creciendo, uno vaya agregando cambios y nuevas funcionalidades, y dilatando un poco los commits. Más allá de que es importante que las historias de usuario con las que un trabaja sean lo más atómicas posibles (dentro de lo razonable), dentro de las mismas es importante realizar los commits apropiadamente por cada cambio específico o nueva funcionalidad, no mezclar cosas. Por ejemplo si estoy trabajando en una nueva funcionalidad y me piden un actualización pequeña que no tiene que ver con la misma, o quizás yo veo algo que corregir que no aplica a la historia que estoy trabajando en ese momento, meter todo en el mismo commit, “total es un cambio chiquito, no pasa nada”.

Hace poco trabajando en un proyecto el cliente nos pidió modificar una relación entre entidades. Originalmente se pidió relacionar “Entidad-A” con “Entidad-B” y se trabajó de esa manera.

Luego de avanzar en el proyecto, el cliente dijo: “En realidad la “Entidad-A” debería estar relacionada con la “Entidad-Z”, cambiemos esa relación. Como podrán imaginarse, no es un cambio sencillo porque implica relaciones y afecta la consistencia en la Base de Datos, y demás.

Se realizó esta modificación solicitada por el cliente. Y se siguió avanzando, hasta que el cliente dijo, “esperen, esto no funciona así, volvamos a la relación ‘Entidad-A’ -> ‘Entidad-B”.

En este punto toma importancia realizar los commits de una forma apropiada.

Realizar nuevamente los cambios necesarios para hacer la modificación implica muchas horas de trabajo, horas que ya se habían invertido, no una, sino dos veces, en la creación y en la primera modificación.

Haciendo uso de las herramientas que nos provee Git, en este caso particular, del comando: “git revert”. Se buscaron los commits específicos que aplicaban el cambio, y se volvió atrás en la “historia” (por suerte en este caso no surgieron conflictos complejos), solamente hizo falta un par de horas para identificar los commits, revertir, comprobar que todo funcione bien y listo.

Ahora bien, si los commits no hubiesen sido hechos sobre los cambios específicos, o no hubiesen tenido títulos apropiados, que describan lo que hace cada commit, esto no hubiese sido posible, hubiese sido mucho más “sucio” el trabajo de revertir o hubiésemos tenido que desarrollar todo nuevamente, insumiendo horas por tercera vez para la misma tarea.

Reglas para hacer un buen commit

⚡ Por esto vamos a repasar algunas reglas que deberíamos seguir a la hora de hacer un commit: (no lo digo yo, lo dicen las buenas prácticas 😉)

Un commit se compone de un asunto (un resumen), un cuerpo y un pie de página, y tanto el cuerpo como el pie de página son opcionales.
El asunto de no debería tener más de 50 caracteres (de hecho, cuando escribimos nuestro mensaje desde la consola GitBash, al llegar a 50 caracteres automáticamente se genera un salto de página y un resaltado rojo.

El asunto es una sola línea que resume lo mejor posible los cambios realizados en el commit.
Resumir los commits es una buena práctica inherente a cualquier sistema de control de versiones. Ayuda a otros (o a nosotros mismo más tarde) a encontrar commits relevantes más rápidamente.
La primera letra del asunto debe ir en mayúscula
No se debe poner un punto “.” Al final de la línea
Se debe poner una línea en blanco entre la línea de asunto y el cuerpo y también entre el cuerpo y el pie de página.
El cuerpo del commit no debería tener mas de 72 caracteres de ancho
Si la descripción de la confirmación no está restringida a 72 caracteres luego, el cuerpo de confirmación ocupará todo el ancho de la línea de comando, lo que hará que el mensaje de confirmación sea más difícil de leer.

El cuerpo se utiliza para proporcionar más detalles sobre los cambios realizados en este commit.
El título del commit debe contestar a la pregunta: “¿qué hace este commit?”
Usar el modo infinitivo, por ejemplo: Agregar; Modificar; Actualizar;
preferentemente los commits deberían estar hechos en inglés, aunque esto dependerá de cada proyecto/empresa en particular
podemos utilizar ciertos prefijos para nuestros títulos dependiendo del objetivo del commit:
feat: cuando se añade una nueva funcionalidad.
fix: cuando se arregla un error.
chore: tareas rutinarias que no sean específicas de una feature o un error como por ejemplo añadir contenido al fichero .gitignore o instalar una dependencia.
test: si añadimos o arreglamos tests.
docs: cuando solo se modifica documentación.
build: cuando el cambio afecta al compilado del proyecto.
ci: el cambio afecta a ficheros de configuración y scripts relacionados con la integración continua.
style: cambios de legibilidad o formateo de código que no afecta a funcionalidad.
refactor: cambio de código que no corrige errores ni añade funcionalidad, pero mejora el código.
perf: usado para mejoras de rendimiento.
revert: si el commit revierte un commit anterior. Debería indicarse el hash del commit que se revierte.
Describir qué y por qué, pero no cómo.
El pie de página sirve para referenciar un ticket o tarea si nuestro repositorio está linkeado a una plataforma de seguimiento como por ejemplo Jira o se puede dejar directamente el link a la definición de la tarea.