Commits que Cuentan una Historia

Un mensaje de commit es la única documentación que viaja con el código para siempre. Los comentarios se eliminan, los wikis quedan obsoletos, los tickets se archivan — pero git log es permanente. Los equipos que escriben buenos commits pueden navegar su propio historial. Los equipos que no lo hacen están haciendo arqueología en su propia base de código en seis meses.

Un buen commit tiene una línea de asunto clara en modo imperativo ("Agregar limitación de tasa al endpoint de autenticación", no "Se agregó limitación de tasa" o "cosas de limitación de tasa"), un cuerpo opcional que explica por qué se hizo el cambio (no qué — el diff muestra qué), y contiene exactamente un cambio lógico.

fix: prevent duplicate webhook deliveries

The webhook dispatcher was firing on both the DynamoDB stream event
and the API Gateway trigger. Deduplicate by checking idempotency key
before dispatch.

Compara eso con lo que la mayoría de los repositorios realmente contienen:

fix stuff
wip
updates

El primer commit es buscable, revertible y se autodocumenta. El segundo conjunto es ruido. Dentro de seis meses, "arreglar cosas" no te dice nada — tendrás que leer el diff, reconstruir el contexto y adivinar la intención. Los 10 segundos que ahorraste escribiendo un mensaje descuidado cuestan 10 minutos cada vez que alguien lo encuentra.

Conventional Commits agrega un prefijo ligero a cada asunto de commit que hace que tu historial sea legible por máquina sin sacrificar la legibilidad humana. El formato es simple:

feat: add dark mode toggle to settings
fix: correct timezone offset in standup scheduler
chore: upgrade TypeScript to 5.7
docs: add API rate-limit documentation
refactor: extract validation logic from route handler

El prefijo te dice la categoría del cambio de un vistazo. feat significa nuevo comportamiento visible para el usuario. fix significa que se corrigió un error. chore significa mantenimiento que no afecta a los usuarios. Esto no cuesta nada — ya estás escribiendo una línea de asunto, solo estás anteponiendo 4–8 caracteres.

El beneficio son changelogs automáticos, versionado semántico (un feat incrementa la versión menor, un fix incrementa el parche), y filtrado instantáneo (git log --grep="^fix:" te muestra cada corrección de error en el último trimestre). Los equipos que adoptan Conventional Commits reportan que sus PRs se revisan más rápido porque el revisor sabe qué tipo de cambio esperar antes de leer una sola línea de diff.

No necesitas herramientas para comenzar. Solo acuerda los prefijos como equipo y aplícalos en la revisión de código. Agrega automatización después si quieres — pero la convención es útil por sí sola.

Un commit debe representar exactamente un cambio lógico. No "todo lo que hice hoy", no "todos los archivos que toqué para esta funcionalidad", y definitivamente no "WIP" — un mensaje que no comunica nada y hace que el commit no sea revertible sin efectos secundarios.

Los commits atómicos importan por dos razones prácticas. Primero, revertibilidad: si un commit hace una cosa, revertirlo deshace una cosa. Si un commit hace tres cosas y una de ellas está rota, revertirlo deshace las tres — incluyendo las dos que estaban bien. Ahora estás arreglando daño colateral de tu propio rollback.

Segundo, bisectabilidad: git bisect busca binariamente en tu historial de commits para encontrar qué commit introdujo un error. Es una de las herramientas de depuración más poderosas de Git — pero solo funciona cuando cada commit es una unidad coherente. Si tus commits mezclan cambios no relacionados, bisect te señalará un commit que contiene tanto el cambio culpable como tres inocentes, y estás de vuelta leyendo diffs manualmente.

El commit "WIP" es el enemigo de ambas propiedades. Dice "no había terminado de pensar" — lo que significa que el commit contiene trabajo parcialmente completado que no puede revertirse limpiamente, no puede bisectarse significativamente, y no puede entenderse de forma aislada. Si necesitas guardar trabajo en progreso, usa git stash o una rama borrador. No contamines el historial compartido con puntos de control que no tienen valor semántico.