Conventional Commits: Cómo escribir mensajes de commit claros, útiles y automatizables

Una buena convención para escribir mensajes de commit no solo mejora la lectura del historial del proyecto, sino que también permite automatizar procesos como generación de changelogs, control de versiones y despliegues. Aquí te presento la especificación Conventional Commits 1.0.0, traducida y explicada para que puedas aplicarla desde hoy.

---

✍️ Estructura del mensaje de commit

<tipo>[opcional ámbito]: <descripción>

[opcional cuerpo del mensaje]

[opcional pie de mensaje (footer)]

Ejemplos

feat: agregar búsqueda por filtros
fix: corregir error de validación en formulario
feat(api)!: eliminar soporte para v1
docs: actualizar sección de instalación en README

---

🧩 Tipos de commit principales

• feat: Se agrega una nueva funcionalidad (↔️ versión minor en SemVer).
• fix: Se corrige un bug (↔️ versión patch en SemVer).
• BREAKING CHANGE: Cambios que rompen compatibilidad (↔️ versión major en SemVer).

Puedes indicar un cambio importante con:

• Un pie de mensaje: BREAKING CHANGE: ahora se requiere Node 18
• O un signo ! tras el tipo o ámbito: feat!: eliminar soporte legacy

---

📌 Tipos adicionales comunes

Basados en la convención Angular:

• build: Cambios en la configuración de build o herramientas externas.
• ci: Cambios en la integración continua.
• docs: Documentación solamente.
• style: Formato, espacios, puntos y coma, etc. (sin cambios en lógica).
• refactor: Refactorización sin cambio de funcionalidad.
• perf: Mejoras de rendimiento.
• test: Agrega o corrige tests.
• chore: Tareas menores sin impacto funcional (por ejemplo, actualización de dependencias).
• revert: Reversión de un commit anterior.

---

🧠 Reglas de estilo

• Usa imperativo: add, fix, remove, etc.
• No uses punto final en el título.
• Mantén el título breve (máximo 50 caracteres).
• Si necesitas contexto adicional, agrégalo en el cuerpo.
• Usa ámbitos opcionales para mayor claridad: feat(api), fix(auth), etc.

---

💡 ¿Por qué usar Conventional Commits?

• ✅ Changelogs automáticos con conventional-changelog
• ✅ Publicación semántica con semantic-release
• ✅ Validación automática con commitlint
• ✅ Flujo de trabajo claro y colaborativo

---

🛠 Herramientas recomendadas

commitlint

Valida que los commits cumplan la convención.

npm install --save-dev @commitlint/{config-conventional,cli}
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1"'

Commitizen

Asistente interactivo para escribir commits con la convención correcta.

npm install -g commitizen
npx commitizen init cz-conventional-changelog --save-dev --save-exact

Husky

Ejecuta scripts antes de commits/pushes (por ejemplo, para validar o testear).

npm install husky --save-dev
npx husky install
npm set-script prepare "husky install"
npm run prepare

---

🧭 Preguntas frecuentes

¿Qué pasa si uso un tipo incorrecto?

• Si todavía no has publicado, puedes hacer git rebase -i y editar el mensaje.
• Si ya lo publicaste, el daño no es fatal. Solo perderás algo de automatización (como el changelog).

¿Puedo inventar mis propios tipos?

Sí, pero solo feat, fix y BREAKING CHANGE afectan directamente la gestión semántica de versiones. Los demás son personalizables.

¿Todos deben seguir esta convención?

No necesariamente. Si usas pull requests con squash & merge, puedes ajustar el mensaje final en el merge sin cargar al resto del equipo.

---

📚 Recomendaciones personales de libros en español sobre Git y GitHub

Aprendiendo Git y GitHub

Desde cero hasta buenas prácticas y estrategias de trabajo en equipo.

Miguel Ángel Durán García

@midudev

Git y GitHub desde cero

Guía de estudio teórico-práctica paso a paso más curso en vídeo.

Brais Moure

@mouredev

---

📚 Recursos

• Conventional Commits – Sitio oficial
• Commitizen
• Commitlint
• Semantic Release
• midudev - Buenas prácticas para escribir commits en Git

---

Adoptar Conventional Commits es una forma simple de ganar claridad, orden y automatización en tus proyectos desde el primer commit. 🚀