Domina tus commits: metodología Conventional Commits

Introducción

En el desarrollo de software profesional, mantener un historial de commits claro y consistente no es solo una buena practica, es una necesidad. La metodología Conventional Commits ofrece un estándar para escribir mensajes de commit que facilitan la colaboración, la automatización y la generación de changelogs. En este artículo, exploraremos qué son los Conventional Commits, por qué son importantes y cómo implementarlos en tus proyectos.

No saben cuántas veces me he encontrado con esta situación en pleno viernes por la tarde: un bug crítico aparece y yo corro al historial de Git esperando encontrar de inmediato el origen del problema… y lo que veo me hace suspirar:

• "arreglo de cosas"
• "update"
• "cambios varios"
• "fix"
• "ya funciona"
• "últimos cambios"

¿Qué se “arregló”? ¿Qué rayos incluye ese “cambios varios”? ¿Y qué significa que “ya funciona”? Momentos así convierten la simple tarea de rastrear un cambio específico en una especie de expedición arqueológica dentro de nuestro propio código.

Un historial de Git desorganizado no es solo una molestia menor. Les cuento que esto puede ser un verdadero lastre:

• Ralentiza el onboarding de nuevos desarrolladores.
• Dificulta el debugging y el rastreo de bugs.
• Imposibilita la generación automática de changelogs.
• Genera confusión en equipos grandes.
• Desaprovecha todo el potencial de las herramientas Git.

Pero, ¿y si existiera una manera de transformar este caos en claridad? ¿Si cada commit contara exactamente qué cambió, por qué y qué impacto tiene?

Es ahí donde entra en juego la metodología Conventional Commits.

Conventional Commits: ¿Qué son?

Esta metodología define un formato específico para los mensajes de commit, estructurándolos de la siguiente manera:

<tipo>[alcance]: <descripción>

[cuerpo opcional]

[pie de página opcional]

El commit contiene los siguientes elementos estructurales para comunicar de manera efectiva los cambios realizados:

• Tipo: Indica la naturaleza del cambio. Algunos tipos comunes incluyen:
  • feat: Nueva funcionalidad.
  • fix: Corrección de errores.
  • docs: Cambios en la documentación.
  • style: Cambios que no afectan el significado del código (espacios en blanco, formato, etc.).
  • refactor: Cambios en el código que no corrigen errores ni agregan funcionalidades.
  • test: Añadir o corregir pruebas.
  • chore: Cambios en tareas de mantenimiento.
• Alcance (opcional): Especifica la parte del código afectada (por ejemplo, un módulo o componente).
• Descripción: Una breve explicación del cambio realizado.
• Cuerpo (opcional): Proporciona detalles adicionales sobre el cambio, si es necesario.
• Pie de página (opcional): Puede incluir referencias a issues o breaking changes.

Breaking Change

Un Breaking Change es una modificación en el código que no es compatible con versiones anteriores, lo que significa que los usuarios o desarrolladores que actualicen a esta nueva versión podrían experimentar fallos o comportamientos inesperados si no ajustan su código o configuración en consecuencia.

Beneficios de usar Conventional Commits

Adoptar esta metodología trae múltiples beneficios:

1. Claridad y Consistencia: Facilita la comprensión del historial de cambios.
2. Automatización: Permite la generación automática de changelogs y versiones semánticas.
3. Generación automática de changelogs: Herramientas como standard-version o semantic-release pueden generar changelogs automáticamente basándose en los mensajes de commit.
4. Mejora la colaboración: Facilita la comunicación entre miembros del equipo.
5. Detección de breaking changes: Ayuda a identificar cambios que pueden afectar la compatibilidad.

Ejemplos prácticos

A continuación, algunos ejemplos de mensajes de commit siguiendo la metodología Conventional Commits:

Nuevo feature

feat(auth): agregar funcionalidad de inicio de sesión con Google

• feat: Indica que se ha añadido una nueva funcionalidad.
• (auth): Especifica que el cambio afecta al módulo de autenticación.
• Descripción clara del cambio realizado.

Corrección de bug

fix(api): corregir error en la validación de datos de usuario

• fix: Indica que se ha corregido un error.
• (api): Especifica que el cambio afecta al módulo de la API.
• La descripción detalla el problema solucionado.

Mantenimiento

chore: actualizar dependencias del proyecto

• chore: Indica que se trata de una tarea de mantenimiento.
• La descripción especifica la acción realizada.

Estilo

style(ui): mejorar el formato de los botones en la interfaz

• style: Indica que se han realizado cambios en el estilo.
• (ui): Especifica que el cambio afecta a la interfaz de usuario.
• La descripción detalla la mejora realizada.

Breaking Change

feat!: migrar sistema de autenticación a JWT


BREAKING CHANGE: las credenciales antiguas ya no funcionan; se requiere actualizar tokens.

• feat!: El signo de exclamación indica que este commit introduce un breaking change.
• El footer proporciona detalles sobre el cambio y sus implicaciones.

Buenas prácticas

No solamente es importante seguir la estructura de Conventional Commits, sino también adoptar algunas buenas prácticas, tales como:

• Sé conciso: Mantén las descripciones breves pero informativas.
• Usa scopes cuando sea relevante: Ayuda a identificar rápidamente qué parte del código se ha modificado.
• Indica breaking changes claramente: Utiliza el formato adecuado para destacar estos cambios.
• Mantén la consistencia: Asegúrate de que todo el equipo siga las mismas reglas.

Tipo	Alcance (Scope)	Cuándo usarlo	Ejemplo de commit
feat	opcional	Para agregar una nueva funcionalidad a tu proyecto	feat(auth): agregar inicio de sesión con OAuth2
fix	opcional	Para corregir un error o bug	fix(parser): corregir error al procesar cadenas vacías
docs	opcional	Para cambios en documentación	docs: actualizar README con instrucciones de instalación
style	opcional	Cambios de formato, espaciado, sangría, etc., que no afectan la lógica	style(ui): ajustar margen en botones del formulario
refactor	opcional	Cambios en el código que no agregan funcionalidades ni corrigen bugs, solo mejoran estructura o legibilidad	refactor(auth): simplificar validación de tokens
test	opcional	Para añadir o modificar pruebas	test(parser): agregar casos para cadenas vacías
chore	opcional	Tareas de mantenimiento o configuración que no afectan código de producción	chore: actualizar dependencias de desarrollo
BREAKING CHANGE	N/A	Para indicar un cambio que rompe compatibilidad con versiones anteriores	BREAKING CHANGE: migración a JWT; credenciales antiguas ya no funcionan

Automatización

Quizá tú, como yo, te has encontrado en la situación de tener varios cambios listos para commit y pensar: “¿Cómo escribo un mensaje claro que siga la convención sin perder tiempo?”

Para mí, la solución ha sido automatizar la generación de commits usando IA directamente desde Neovim. La idea es simple: hago mis cambios, los pongo en staging y dejo que Copilot Chat me sugiera un mensaje de commit siguiendo la convención de Conventional Commits.

El flujo que uso es este:

1. Detectar el ticket o referencia del cambio (por ejemplo un número de incidencia o tarea).
2. Analizar los cambios staged en Git.
3. Generar un mensaje de commit automático que respete los tipos (feat, fix, docs, etc.), los scopes y un resumen claro del cambio.
4. Mostrar el mensaje en una ventana flotante para poder aprobarlo o cancelarlo.
5. Ejecutar git commit solo si apruebo el mensaje.

Esto me permite:

• Ahorrar tiempo, porque no tengo que pensar cada mensaje.
• Mantener consistencia en todo mi historial de commits.
• Aplicar correctamente breaking changes, scopes y tipos.
• Tener un historial de Git que es claro, profesional y útil para automatización de changelogs o versionado semántico.

Aquí un ejemplo de cómo lo tengo configurado en Neovim:

vim.keymap.set("n", ";ccg", commit_with_ai, { desc = "AI Generate Commit" })

Conclusión

Un historial de commits limpio no es solo una cuestión estética, sino una herramienta poderosa para la productividad, la colaboración y la calidad del software. Adoptar Conventional Commits permite que tu equipo trabaje de manera más eficiente, automatice tareas tediosas y reduzca errores en producción.

Si aún no lo aplicas en tus proyectos, te recomiendo probarlo en un repositorio pequeño primero. Notarás la diferencia en la organización y trazabilidad de tus cambios.

Referencias

Conventional Commits Specification|Semantic Versioning

"Los programas deben escribirse para que las personas los lean, y solo incidentalmente para que las máquinas los ejecuten."

— Harold Abelson