Conventional Commits: cómo escribir mensajes de commit claros, útiles y automatizables
Tener una convención para los mensajes de commit hace que el historial del proyecto se lea mucho mejor, y además permite automatizar cosas como el changelog, el control de versiones o los despliegues. Aquí va la especificación Conventional Commits 1.0.0, traducida y explicada para que puedas usarla desde ya.
Estructura del mensaje
<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 READMETipos principales
feat: se agrega una funcionalidad nueva (versión minor en SemVer).fix: se corrige un bug (versión patch en SemVer).BREAKING CHANGE: cambios que rompen la 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
Otros tipos habituales
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
- Escribe en imperativo o infinitivo:
add,fix,remove, o en españolagregar,corregir,eliminar. - No pongas punto final en el título.
- Mantén el título breve, de 50 caracteres como mucho.
- Si hace falta más contexto, ponlo en el cuerpo.
- Usa ámbitos cuando ayuden a aclarar:
feat(api),fix(auth), etc.
Para qué sirve
Además de un historial más fácil de leer, la convención permite que las herramientas trabajen por ti: changelogs automáticos con conventional-changelog, versiones y publicaciones con semantic-release y validación de los mensajes con commitlint. Cómo montar todo eso lo cuento en Del commit al changelog.
Herramientas
commitlint
Valida que los commits cumplan la convención.
npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo 'npx --no -- commitlint --edit $1' > .husky/commit-msgCommitizen
Asistente interactivo para escribir commits con la convención correcta.
npm install -g commitizen
npx commitizen init cz-conventional-changelog --save-dev --save-exactHusky
Ejecuta scripts antes de commits/pushes (por ejemplo, para validar o testear).
npm install --save-dev husky
npx husky inithusky init crea la carpeta .husky/ y añade el script prepare al package.json, así que conviene ejecutarlo antes de configurar commitlint.
Preguntas frecuentes
¿Qué pasa si uso un tipo incorrecto?
- Si todavía no lo has subido, puedes usar
git rebase -iy editar el mensaje. - Si ya lo subiste, no pasa nada grave: solo pierdes algo de automatización, como que ese cambio no salga en 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.
