Conventional Commits: Cómo Escribir Mensajes de Git Profesionales
Domina el estándar de la industria (feat, fix, chore, refactor, breaking change) para historiales legibles y changelogs 100% automáticos.
En proyectos sin estándares de ingeniería, el historial de Git suele llenarse de mensajes caóticos e inútiles como: `arreglos`, `update`, `subiendo cambios`, `ahora si funciona` o `por fin terminado`. Tres meses después, ningún programador del equipo (ni tú mismo) tiene la menor idea de qué se cambió exactamente en cada punto de la historia. **Conventional Commits** es una especificación formal y ligera basada en Semantic Versioning que define una convención estructurada para redactar mensajes de commit legibles tanto por seres humanos como por herramientas automatizadas. Al estructurar tus mensajes bajo este estándar, herramientas de CI/CD pueden inspeccionar tu historial y **generar automáticamente archivos CHANGELOG.md**, determinar si la siguiente versión debe ser un parche o una versión mayor, y publicar releases sin intervención manual.
- ✓Historial Limpio y Escaneable: Con un simple vistazo a `git log --oneline` puedes saber exactamente qué se añadió, qué se arregló y qué se refactorizó.
- ✓Automatización Total de Releases: Herramientas como Semantic Release calculan automáticamente si corresponde una versión `v1.0.1`, `v1.1.0` o `v2.0.0` analizando los prefijos de tus commits.
- ✓Facilidad para Búsquedas y Auditorías: Permite filtrar instantáneamente todos los bugs corregidos en los últimos 6 meses usando comandos simples de terminal.
- •Erradica para siempre los mensajes ambiguos de una sola palabra que frustran a los revisores de código.
- •Acelera la incorporación de nuevos desarrolladores al equipo de desarrollo.
- •Comunica con total transparencia a los usuarios y clientes qué novedades incluye cada actualización.
Imagina que llevas tu automóvil al taller mecánico. Cuando te devuelven el vehículo, el mecánico te entrega una factura que solo dice: *'Trabajos varios hechos'*. Tú no sabes si cambiaron los frenos, si le cambiaron el aceite o si le cambiaron una lámpara de luz. En un taller profesional certificado, te entregan una hoja con casillas estructuradas: - `[REPARACIÓN] (Frenos): Se cambiaron las pastillas desgastadas` - `[MEJORA] (Audio): Se instaló un estéreo con Bluetooth nuevo` - `[MANTENIMIENTO] (Motor): Cambio de filtro y aceite 5W30` Al mirar la hoja, sabes exactamente qué se hizo, en qué parte del auto y qué nivel de atención requiere.
Explicación Paso a Paso del Tema
Estructura Oficial del Mensaje
Un mensaje de Conventional Commits sigue la siguiente plantilla estricta: `<tipo>[ámbito opcional]: <descripción en imperativo>` `[cuerpo largo opcional]` `[pie de página con breaking changes u orden de issue]`
La primera línea no debe superar los 50-72 caracteres y se redacta en tiempo presente o imperativo sin punto final.
feat(auth): agregar soporte para inicio de sesión con Google OAuth Permite a los usuarios registrarse e iniciar sesión utilizando su cuenta corporativa de Google. Valida el token ID mediante la API de Google Identity. Closes #142
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| feat(auth): | Encabezado | Tipo de cambio (nueva función) y ámbito afectado (módulo de autenticación). |
| Closes #142 | Footer | Comando que cierra automáticamente el issue correspondiente en GitHub al fusionarse. |
Los tipos principales son: `feat` (nueva función), `fix` (corrección de bug), `docs` (documentación), `style` (formato/espacios), `refactor` (reestructuración sin cambiar comportamiento), `perf` (rendimiento), `test` (pruebas) y `chore` (tareas de mantenimiento o dependencias).
Cómo Señalizar un Breaking Change (Ruptura de Compatibilidad)
Para indicar que un cambio rompe la compatibilidad anterior (obligando a subir la versión MAJOR en SemVer), agrega un signo de exclamación `!` después del tipo o incluye una sección `BREAKING CHANGE:` en el pie.
Esto alerta inmediatamente a los pipelines y a los usuarios.
feat(api)!: cambiar el formato de respuesta de /users de XML a JSON BREAKING CHANGE: El endpoint /users ya no devuelve respuestas en XML. Todos los clientes deben actualizar sus parsers a JSON.
| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| feat!: | Ruptura de Compatibilidad | El signo de exclamación advierte a los sistemas automáticos que incrementen el número MAJOR. |
Escribir la descripción en pasado (ej. `fixed bug`): la convención universal aconseja usar presente imperativo (ej. `fix: corregir error en cálculo de impuestos`).
Hacer Cumplir las Reglas con Commitlint
Instala `@commitlint/cli` y `@commitlint/config-conventional` para que Git rechace cualquier commit que no cumpla con la estructura formal.
Se vincula a través de Husky en el gancho `commit-msg`.
npm install --save-dev @commitlint/cli @commitlint/config-conventional
echo "module.exports = { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'| Parámetro / Flag | Tipo / Rol | Significado y Uso |
|---|---|---|
| commitlint | Validador | Analiza el texto del mensaje y aborta el commit si el prefijo o la estructura son inválidos. |
Si alguien intenta hacer `git commit -m "arreglos varios"`, commitlint cancelará el commit en 50 milisegundos con un mensaje de ayuda explicando la sintaxis correcta.
Casos Prácticos Reales en Producción
Situaciones de ingeniería reales sin mención de presupuestos ficticios.
1Generación de Changelogs Automáticos en una Librería de Código Abierto
Los mantenedores de una librería pasaban 4 horas al final de cada mes leyendo cientos de commits para redactar a mano el archivo CHANGELOG de cada versión.
Adoptaron Conventional Commits e implementaron `semantic-release` en GitHub Actions.
Fichas Nemotécnicas de Conceptos Clave
Glosario rápido para recordar los términos fundamentales de la lección.
Especificación formal para dar significado estructurado a los mensajes de commit en repositorios Git.
Herramienta que analiza y asegura que los mensajes de commit se adhieran a las reglas semánticas definidas.
Archivo histórico que documenta de forma cronológica todas las novedades, mejoras y correcciones de un software.
Conventional Commits: Cómo Escribir Mensajes de Git Profesionales
Selecciona una opción para autoevaluarte al instante. La respuesta se califica de inmediato.
¿Qué prefijo debe utilizarse bajo el estándar de Conventional Commits cuando agregas una nueva funcionalidad para los usuarios?
¿Qué indica colocar un signo de exclamación (!) antes de los dos puntos (ejemplo: 'feat(api)!:...')?
¿Cuál de los siguientes mensajes de commit cumple estrictamente con el estándar de Conventional Commits?
Preguntas Frecuentes (FAQ)
¿Qué tipo de commit debo usar si solo actualicé dependencias de NPM o configuré TypeScript?
Se utiliza el tipo `chore:` (ej. `chore(deps): actualizar axios a v1.7.0`) o `build:` (ej. `build(ts): habilitar modo estricto en tsconfig`). No alteran la lógica de negocio ni agregan features.
¿Debo escribir los commits en español o en inglés?
La inmensa mayoría de proyectos profesionales globales utilizan inglés (`feat: add login with oauth`), pero si el estándar de tu empresa exige español, lo fundamental es la consistencia: mantén siempre los tipos estándar (`feat:`, `fix:`) y redacta la descripción en el idioma acordado por el equipo.