Estructura del mensaje
<type>(<scope>): <subject>
─────────────────────────────────────────────
<body>
─────────────────────────────────────────────
<footer>
Header — obligatorio
El tipo, scope y subject. Máximo 100 caracteres en total por línea.
Subject — imperativo
"Add feature" no "Added feature". Primera letra en mayúscula. Sin punto final. Máx 70 chars.
Body — explica el por qué
Qué cambia y por qué, no cómo. Saltos de línea reales (nunca
\n literal).
Tipos de commit
feat
Nueva funcionalidad o feature para el usuario
fix
Corrección de bug que afecta al funcionamiento
ref
Refactoring sin cambio de comportamiento
perf
Mejora de rendimiento (velocidad, memoria…)
docs
Solo documentación (README, JSDoc, comentarios)
test
Añadir o corregir tests — sin cambio de lógica
build
Build system, dependencies o scripts de build
ci
Configuración de CI/CD (GitHub Actions, etc.)
chore
Tareas de mantenimiento sin impacto funcional
style
Formato de código (espacios, comas) sin lógica
license
Cambios de licencia o archivos LICENSE
Ejemplos reales — proyecto cultivaia-web
🔴 fix — corrección de bug
fix(checkout): Handle null price for free resources
Lemon Squeezy returns null when the product has a
0€ price, causing a crash on the checkout button.
Add null-safe fallback before rendering CTA.
🟢 feat — nueva funcionalidad
feat(recursos): Add filter by category on resources page
Implement client-side filtering using Astro
content collections. Filter by servicio (Web,
Marketing, IA) without reloading the page.
🟡 perf — optimización
perf(images): Switch hero images to WebP with lazy loading
Replace PNG hero images with WebP equivalents.
Add loading="lazy" to below-fold images.
LCP drops from 3.2s to 1.1s on mobile.
🔴 feat! — breaking change
feat(api)!: Remove legacy /api/recursos/v1 endpoints
Remove all v1 endpoints deprecated since v0.5.
Clients (Skills dashboard) should migrate to v2.
🔵 ref — refactoring
ref(skills): Extract SkillCard into shared component
Move duplicate SkillCard markup from recursos/
and servicios/ pages into components/SkillCard.astro.
No behavior change.
🔵 ci — integración continua
ci: Add Lighthouse score gate to PR checks
Block merge if Performance or Accessibility drops
below 90. Runs in GitHub Actions on PR opened/sync.
Threshold configurable via .lighthouse.json.
✓ Correcto
feat(checkout): Add discount code input field
fix(nav): Prevent mobile menu from staying open on route change
docs: Update README with local setup instructions
chore(deps): Bump astro from 4.6 to 4.8
ref(utils): Extract slug formatter to lib/format.ts
✗ Incorrecto
arreglado bug en checkout
cambios varios
WIP.
fix: fixed the thing that was broken yesterday
Update: updated some components and styles etc
Principios del equipo
Un commit = un cambio estable
Cada commit debe compilar y funcionar por sí solo. Sin "WIP" mezclados con fixes reales.
Independientemente revisable
El revisor debe entender qué y por qué sin leer el código completo. El mensaje es la documentación.
Sin datos de cliente en commits
Nunca nombres de cliente, emails ni PII. Describe el síntoma técnico; usa el ticket interno (GH-xxx).
Rama antes de commitear
Verificar git branch --show-current. Si estás en main/master, crear branch primero.
Imperativo presente siempre
"Add", "Fix", "Remove" — no "Added", "Fixed" ni "Removing". El commit dice qué hace, no qué hizo.