Conventional Commits

Conventional Commits es una especificación ligera sobre los mensajes de commit. Proporciona un conjunto de reglas para crear un historial de commits explícito, lo que facilita la escritura de herramientas de automatización.

En HERA, adoptar este estándar es obligatorio porque nos permite:

• Generar CHANGELOGs automáticamente.
• Determinar el versionamiento semántico (SemVer) de forma automática con cada release.
• Comunicar la naturaleza de los cambios a compañeros de equipo, público y otros stakeholders.
• Disparar procesos de build y despliegue de forma predecible.

---

Estructura del Mensaje

El formato de un commit convencional es simple:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

---

Componentes Principales

1. Type (Tipo - Obligatorio)

Define la categoría del cambio. Estos son los tipos permitidos en HERA:

Tipo	Título	Descripción
feat	Features	Una nueva funcionalidad para el usuario.
fix	Bug Fixes	Una corrección de un bug en producción.
docs	Documentation	Cambios que solo afectan a la documentación.
style	Styles	Cambios que no afectan el significado del código (espacios, formato, etc).
refactor	Code Refactoring	Un cambio en el código que no corrige un bug ni añade una funcionalidad.
perf	Performance	Un cambio que mejora el rendimiento.
test	Tests	Añadir tests que faltan o corregir tests existentes.
build	Build System	Cambios que afectan el sistema de build o dependencias externas.
chore	Chores	Otros cambios que no modifican el código src o de test.
revert	Reverts	Revierte un commit anterior.

2. Scope (Ámbito - Opcional)

El ámbito proporciona información contextual adicional. Es una palabra entre paréntesis después del tipo, que describe la sección del código afectada.

feat(auth): add password reset functionality
fix(checkout): validate credit card number
test(api): add integration tests for user endpoint

3. Description (Descripción - Obligatorio)

Es un resumen corto del cambio de código.

• Usa el imperativo, tiempo presente: “add” no “added” ni “adds”.
• No capitalices la primera letra.
• Sin punto (.) al final.

✅  fix(login): redirect user on session timeout
❌  Fixed the login redirection issue.

4. Body (Cuerpo - Opcional)

El cuerpo del mensaje es para proporcionar contexto adicional sobre el cambio. Explica el “qué” y el “por qué”, no el “cómo”.

5. Footer (Pie - Opcional)

El pie se usa para referenciar IDs de seguimiento de issues (como Jira) o para declarar BREAKING CHANGES.

---

Breaking Changes

Un cambio que rompe la compatibilidad con versiones anteriores DEBE indicarse en el pie del commit. Un BREAKING CHANGE puede ser parte de commits de cualquier type.

Debe empezar con el texto BREAKING CHANGE: seguido de una descripción de lo que ha cambiado.

feat: change user ID from number to UUID

BREAKING CHANGE: The `id` field on the User model is now a UUID string
instead of an auto-incrementing integer. All services consuming the
User API must be updated to handle UUIDs.

Alternativamente, se puede usar un ! después del tipo/ámbito para llamar la atención sobre el breaking change: feat(api)!: ...

---

Versionamiento Semántico (SemVer)

La principal ventaja de usar Conventional Commits es que nos permite automatizar el versionamiento.

• fix se correlaciona con PATCH en SemVer. (ej. 1.2.3 → 1.2.4)
• feat se correlaciona con MINOR en SemVer. (ej. 1.2.3 → 1.3.0)
• BREAKING CHANGE (o un ! después del tipo) se correlaciona con MAJOR en SemVer. (ej. 1.2.3 → 2.0.0)

Automatización en HERA

El pipeline de release en HERA usa el historial de commits desde el último tag para calcular automáticamente la siguiente versión del software y generar un CHANGELOG.md detallado.