Elaborando Mensajes de Commit Excelentes en Git: Mejores Prácticas para un Historial Claro

Los mensajes de commit de Git son las notas de las que depende tu equipo cuando el código se rompe, el comportamiento cambia o un lanzamiento necesita explicación. Un mensaje claro te dice qué cambió y por qué, sin obligarte a aplicar ingeniería inversa al diff.

Los buenos mensajes de commit no necesitan ser sofisticados. Necesitan una línea de asunto útil, suficiente contexto para cambios no triviales y un estilo consistente que tu equipo pueda leer meses después.

¿Por Qué Son Importantes los Buenos Mensajes de Commit?

Los buenos mensajes de commit ayudan de varias maneras prácticas:

Comprensión de los Cambios: Proporcionan contexto inmediato sobre lo que un commit específico introduce o modifica, ahorrando tiempo al revisar código o recordar decisiones pasadas.
Depuración: Al rastrear errores, un historial de commits claro te permite identificar exactamente cuándo y por qué se introdujo un cambio problemático.
Colaboración: Para los miembros del equipo que se unen a un proyecto o revisan código antiguo, los mensajes bien escritos facilitan la comprensión de la trayectoria de desarrollo del proyecto.
Revisiones de Código: Ofrecen a los revisores una visión de la intención detrás de los cambios, facilitando una retroalimentación más productiva y enfocada.
Herramientas Automatizadas: Muchas herramientas de Git, como los generadores de changelog y los creadores de notas de lanzamiento, dependen de los mensajes de commit para funcionar de manera efectiva.
Registro Histórico: Sirven como una forma de documentación, preservando la evolución de la base de código a lo largo del tiempo.

La Anatomía de un Mensaje de Commit Excelente en Git

Una estructura universalmente reconocida para los mensajes de commit de Git sigue un patrón simple pero poderoso: una línea de asunto concisa seguida de un cuerpo opcional más detallado.

La Línea de Asunto

La línea de asunto es la primera línea de tu mensaje de commit. Debe ser un resumen breve e imperativo de los cambios. Piénsalo como un título para el commit.

Directrices Clave para la Línea de Asunto:

Mantenlo conciso: Alrededor de 50 caracteres es un objetivo útil, no un límite estricto. Mantén el asunto lo suficientemente corto para escanearlo en git log --oneline.
Usa el modo imperativo: Comienza con un verbo que describa la acción, como si estuvieras dando una orden. Ejemplos: Corrige, Agrega, Refactoriza, Actualiza, Elimina, Estiliza.
Escribe la primera palabra en mayúscula: La convención estándar dicta poner en mayúscula la primera letra de la línea de asunto.
No termines con un punto: La línea de asunto es un título, no una oración.
Evita usar git commit -m "mensaje" para mensajes largos: Aunque es conveniente para notas cortas, puede llevar a mensajes menos estructurados. Usa git commit sin argumentos para abrir tu editor y redactar mensajes más complejos.

Ejemplos de Buenas Líneas de Asunto:

feat: agrega módulo de autenticación de usuario
fix: resuelve bucle infinito en el procesamiento de datos
docs: actualiza pasos de instalación en el README
refactor: simplifica la carga de imágenes
chore: actualiza dependencias de desarrollo

El Cuerpo

El cuerpo del mensaje de commit es donde proporcionas más contexto y detalle. Está separado de la línea de asunto por una línea en blanco. Esta sección es opcional pero muy recomendada para cualquier cosa más allá de cambios triviales.

Directrices Clave para el Cuerpo:

Explica el 'por qué' y el 'cómo': No solo describas qué cambió; explica por qué el cambio fue necesario y cómo se implementó. ¿Qué problema resuelve este commit? ¿Cuál era el comportamiento anterior? ¿Cuál es el nuevo comportamiento?
Ajusta las líneas a 72 caracteres: Esta es una convención de larga data que mejora la legibilidad en muchas herramientas y terminales de Git.
Usa viñetas para listas: Si necesitas enumerar múltiples cambios o puntos, usa viñetas para mayor claridad.
Referencia issues o tickets: Si el commit se relaciona con un rastreador de incidencias (ej. GitHub Issues, Jira), incluye el número del ticket para la trazabilidad.

Ejemplo de un Buen Mensaje de Commit (Asunto + Cuerpo):

feat: implementa la página de perfil de usuario

Este commit introduce la página de perfil de usuario, permitiendo a los
usuarios ver y editar su información personal.

Anteriormente, los usuarios no podían acceder ni modificar los detalles
de su perfil. Este cambio agrega una nueva ruta (`/profile`) y un
componente correspondiente que obtiene los datos del usuario desde la
API y proporciona formularios para actualizar campos como nombre,
correo electrónico y biografía.

Relacionado con #123.

Tipos Comunes de Mensajes de Commit (Commits Convencionales)

Seguir una convención para los tipos de mensajes de commit puede mejorar aún más la claridad y habilitar herramientas automatizadas. La especificación Commits Convencionales es un estándar popular que promueve un enfoque estructurado.

Los Commits Convencionales usan un prefijo para denotar el tipo de cambio:

feat (característica): Se introduce una nueva funcionalidad en la base de código.
fix (corrección de error): Se resuelve un error.
docs (documentación): Cambios solo en la documentación.
style (formato): Cambios que no afectan el significado del código (espacios en blanco, formato, punto y coma faltantes, etc.).
refactor (refactorización de código): Un cambio de código que no corrige un error ni agrega una funcionalidad.
perf (rendimiento): Un cambio de código que mejora el rendimiento.
test (agregar pruebas faltantes o corregir pruebas existentes): Agregar o corregir pruebas.
build (cambios que afectan el sistema de compilación o dependencias externas): Ejemplos son scripts de npm, webpack, etc.
ci (cambios en nuestros archivos y scripts de configuración de CI): Ejemplos son Travis, Circle, BrowserStack, SauceLabs, etc.
chore (tareas de mantenimiento): Tareas que no encajan en los otros tipos, como el mantenimiento del repositorio.

Ámbito (Opcional): Se puede agregar un ámbito al prefijo para indicar la parte de la base de código afectada. Por ejemplo: feat(auth): Agrega autenticación JWT.

Pie de Página (Opcional): Usa el pie de página para referenciar issues, marcar cambios disruptivos o agregar otros metadatos. Los Commits Convencionales usan BREAKING CHANGE: para cambios disruptivos.

Ejemplo usando Commits Convencionales:

fix(api): corrige el endpoint para la recuperación de datos de usuario

Anteriormente, el endpoint `/users/:id/data` devolvía información
desactualizada. Este commit actualiza el endpoint a `/users/:id/profile`
el cual obtiene los datos de perfil de usuario más actuales.

Cierra #456

Consejos para Escribir Buenos Mensajes de Commit

Haz commits con frecuencia, pero de forma lógica: Realiza commits pequeños y atómicos que representen un único cambio lógico. Esto facilita la escritura y comprensión de los mensajes.
Escribe los mensajes desde la perspectiva del futuro del proyecto: Imagina que estás revisando este commit dentro de seis meses. ¿Qué información necesitarías para entender el cambio rápidamente?
Sé específico: Evita mensajes vagos como "Actualizar código" o "Correcciones de errores". Explica con precisión qué se actualizó o corrigió.
Usa comillas invertidas para referencias de código: Si mencionas nombres de archivos, funciones o nombres de variables, enciérralos entre comillas invertidas (`).
Revisa tus mensajes: Antes de hacer el commit, tómate un momento para leer tu mensaje. ¿Tiene sentido? ¿Es claro?

Conclusión

Escribe cada mensaje de commit para la persona que lo leerá durante una revisión, reversión o incidente. Usa un asunto imperativo corto, agrega un cuerpo cuando la razón no sea obvia y mantén cada commit enfocado en un único cambio lógico.