Commitlint
Commitlint es la única de estas herramientas que no mira tu código: mira el mensaje de tus commits. Su trabajo es rechazar el commit si el mensaje no sigue la convención acordada.
Por qué importa el mensaje
Section titled “Por qué importa el mensaje”a1b2c3d cambiosd4e5f6a fix7g8h9i0 ya funciona1j2k3l4 subiendo lo de ayera1b2c3d feat(checkout): añadido pago con Stripe Linkd4e5f6a fix(cart): corregido el cálculo del IVA con descuento7g8h9i0 refactor(api): extraída la lógica de precios a un composable1j2k3l4 docs(readme): documentado el flujo de suscripciónEl segundo historial se puede leer, filtrar (git log --grep "feat(checkout)") y usar para generar un changelog automáticamente. El primero no sirve para nada.
Conventional Commits: la estructura
Section titled “Conventional Commits: la estructura”La convención que usamos se llama Conventional Commits. Un mensaje válido tiene esta forma:
tipo(ámbito): descripción
[cuerpo opcional]
[pie opcional]-
tipo— qué clase de cambio es. Es obligatorio y solo puede ser uno de una lista cerrada. -
(ámbito)— a qué parte del proyecto afecta. Va entre paréntesis. En Alebat es obligatorio. -
:+ espacio — separador. Literalmente dos puntos y un espacio. -
descripción— qué has hecho, en una línea.
Los tipos permitidos
Section titled “Los tipos permitidos”| Tipo | Cuándo se usa |
|---|---|
feat | Una funcionalidad nueva para el usuario. |
fix | La corrección de un bug. |
docs | Cambios solo en documentación. |
style | Formato, espacios, comas. Nada que cambie el comportamiento. |
refactor | Reescritura de código que no añade funcionalidad ni corrige bugs. |
perf | Un cambio cuyo objetivo es mejorar el rendimiento. |
test | Añadir o corregir tests. |
build | Cambios en el sistema de build o en dependencias. |
ci | Cambios en la configuración de integración continua (workflows, pipelines). |
chore | Tareas de mantenimiento que no encajan en nada de lo anterior (releases, etc.). |
revert | Revertir un commit anterior. |
Ejemplos válidos y no válidos
Section titled “Ejemplos válidos y no válidos”✅ feat(checkout): añadido el selector de método de pago✅ fix(i18n): corregida la traducción del botón de compra en catalán✅ docs(coemCourses): añadida documentación de los cursos de COEM✅ chore(release): release 1.2.0
❌ arreglado el bug del carrito → falta tipo y ámbito❌ fix: corregido el carrito → falta el ámbito (scope-empty)❌ Fix(cart): corregido el carrito → el tipo va en minúscula❌ feat(cart):añadido el cupón → falta el espacio tras los dos puntos❌ update(cart): añadido el cupón → 'update' no es un tipo permitidoCómo funciona técnicamente
Section titled “Cómo funciona técnicamente”Commitlint no se ejecuta solo: lo lanza el hook commit-msg de Git, que instala Husky. Ese hook contiene una única línea:
npx --no -- commitlint --edit "$1"$1es la ruta al archivo temporal donde Git ha guardado el mensaje que acabas de escribir (normalmente.git/COMMIT_EDITMSG).--editle dice a Commitlint que lea el mensaje de ese archivo.--noevita quenpxintente descargar el paquete de internet: sicommitlintno está instalado en el proyecto, falla en lugar de instalarlo por su cuenta.
Si Commitlint devuelve un error, el hook devuelve un código de salida distinto de cero y Git aborta el commit. Tu mensaje no se pierde: se queda en .git/COMMIT_EDITMSG y puedes recuperarlo con git commit -e -F .git/COMMIT_EDITMSG.
Salida de un error típico
Section titled “Salida de un error típico”⧗ input: fix: corregido el carrito✖ scope may not be empty [scope-empty]
✖ found 1 problems, 0 warningsⓘ Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlintEntre corchetes aparece el nombre de la regla que has incumplido, que es la forma rápida de saber qué corregir.
Dónde están nuestras reglas
Section titled “Dónde están nuestras reglas”En Alebat las reglas no se escriben en cada proyecto. Viven en el paquete @alebat/default-alebat-config y cada repositorio las importa en tres líneas:
import { commitLintFront } from '@alebat/default-alebat-config'
export default commitLintFrontEl análisis completo de esa configuración está en default-alebat-config.
Comprobar un mensaje sin hacer commit
Section titled “Comprobar un mensaje sin hacer commit”# Validar un mensaje concretoecho "feat(cart): añadido el cupón" | npx commitlint
# Validar los mensajes de los últimos commits de tu ramanpx commitlint --from HEAD~5 --to HEAD --verboseEsto último es útil antes de abrir un Pull Request, para asegurarte de que todo el historial de la rama es válido.