Conventional Commits: cómo escribir buenos mensajes de commit

Abre el historial de un proyecto viejo y probablemente vas a encontrar mensajes como ajustes, wip y ahora sí. No le dicen nada a quien necesite entender el código dentro de seis meses. Conventional Commits es un estándar simple que resuelve eso.

El formato

Cada mensaje sigue esta estructura:

<tipo>(<alcance opcional>): <descripción>

<cuerpo opcional>

<pie opcional>

Ejemplos:

feat(login): agrega inicio de sesión con Microsoft
fix(api): corrige timeout en la exportación a CSV
docs: explica cómo ejecutar las pruebas localmente

Los tipos más usados

feat: una funcionalidad nueva para quien usa el producto.
fix: corrección de un bug.
docs: solo documentación.
refactor: un cambio en el código que no altera el comportamiento.
perf: mejora de rendimiento.
test: pruebas nuevas o corregidas.
build y ci: sistema de build, dependencias y pipelines.
chore: tareas que no entran en las categorías anteriores.

Alcance y descripción

El alcance dice dónde ocurrió el cambio: feat(checkout), fix(auth). Acuerda los alcances con tu equipo.
Escribe la descripción en presente: agrega, corrige, elimina.
Sé específico: corrige el cálculo del envío para direcciones sin número es mejor que corrige envío.
Mantén la primera línea corta, de unos 72 caracteres como máximo. Los detalles van en el cuerpo.

Cuerpo y pie

El cuerpo explica el porqué del cambio, no qué cambió línea por línea (eso ya lo muestra el diff). El pie guarda referencias, como el número de la tarea:

fix(checkout): recalcula el envío al cambiar la dirección

El envío se quedaba con el valor de la dirección anterior cuando la persona
cambiaba el código postal después de elegir la entrega.

Refs: #482

Breaking changes

Cuando el cambio rompe la compatibilidad, márcalo con ! después del tipo o con BREAKING CHANGE: en el pie:

feat(api)!: elimina el endpoint /v1/pedidos

BREAKING CHANGE: usa /v2/pedidos, que pagina los resultados.

Por qué vale la pena

El historial se convierte en documentación: puedes leer qué cambió entre dos versiones.
Herramientas como semantic-release y release-please generan el changelog automáticamente.
La versión también se puede calcular sola: fix sube el patch, feat sube el minor y un breaking change sube el major.
La revisión de código se vuelve más fácil, porque el tipo ya dice qué esperar del diff.

Cómo adoptarlo en tu equipo

Acuerda los tipos y alcances con tu equipo y escríbelos en el README o en la guía de contribución.
Valida los mensajes con commitlint, en el hook de commit o en el pipeline.
Empieza por los tipos principales (feat, fix, docs, refactor) y agrega los demás cuando los necesites.

Mensajes de commit con IA en GitMuninn

Escribir un buen mensaje cada vez cuesta trabajo. En GitMuninn, la IA lee el diff y sugiere el mensaje del commit, que tú revisas antes de confirmar. Solo se ejecuta cuando se lo pides, recibe únicamente el diff y el mensaje, y no se guarda nada en ningún servidor. Son 20 mensajes al mes en el plan Gratis y sin límite en Pro y Business.