# Conventional Commits - Guía Completa

## Estructura Básica

El mensaje de commit debe estructurarse de la siguiente manera:

```
<tipo>[alcance opcional]: <descripción>

[cuerpo opcional]

[pie opcional]
```

## Tipos de Commits

| Tipo | Descripción | Ejemplo |
|------|-------------|---------|
| **feat** | Nueva funcionalidad | `feat(auth): add JWT authentication` |
| **fix** | Corrección de bug | `fix(api): resolve null pointer exception` |
| **docs** | Cambios en documentación | `docs(readme): update installation guide` |
| **style** | Cambios de formato/estilo | `style(css): fix button alignment` |
| **refactor** | Refactorización de código | `refactor(service): simplify user validation` |
| **test** | Agregar o modificar tests | `test(user): add unit tests for service` |
| **chore** | Mantenimiento/configuración | `chore(deps): update dependencies` |
| **perf** | Mejoras de performance | `perf(db): optimize query performance` |
| **ci** | Cambios en CI/CD | `ci(github): add automated testing` |
| **build** | Cambios en build/dependencias | `build(npm): update webpack config` |
| **revert** | Revertir commit anterior | `revert: feat(auth): add JWT authentication` |

## Reglas y Mejores Prácticas

### Formato de la Descripción
- Usar **presente imperativo** ("add" no "added" o "adding")
- **No capitalizar** la primera letra
- **No usar punto final**
- **Máximo 50 caracteres** para la descripción
- Ser **específico y descriptivo**

### Ejemplos Correctos
```
feat(user): add email verification functionality
fix(auth): resolve token expiration bug
docs(api): add endpoint documentation
style(header): improve responsive design
refactor(utils): extract common validation logic
test(payment): add integration tests
chore(config): update ESLint rules
```

### Ejemplos Incorrectos
```
❌ Fix bug                    (muy general)
❌ Added new feature.         (tiempo pasado y punto final)
❌ FEAT: Add login           (capitalización incorrecta)
❌ feat: This is a very long description that exceeds the character limit
```

## Alcance (Scope)

El alcance es opcional pero recomendado para proyectos grandes:

```
feat(auth): add password reset
fix(database): resolve connection timeout
docs(contributing): update PR guidelines
```

### Ejemplos de Alcances Comunes
- **auth** - autenticación/autorización
- **api** - endpoints de API
- **ui** - interfaz de usuario
- **db/database** - base de datos
- **config** - configuración
- **security** - seguridad
- **performance** - optimizaciones

## Cuerpo del Mensaje

Para cambios complejos, incluir un cuerpo explicativo:

```
feat(payment): add Stripe integration

- Add Stripe SDK configuration
- Implement payment processing workflow
- Add error handling for failed payments
- Update payment status tracking

Closes #123
```

## Breaking Changes

Para cambios que rompen la compatibilidad:

```
feat(api)!: change user endpoint structure

BREAKING CHANGE: The user API now returns nested objects instead of flat structure.

Old: { "name": "John", "email": "john@example.com" }
New: { "profile": { "name": "John", "email": "john@example.com" } }
```

## Pies de Mensaje

### Referencias a Issues
```
fix(auth): resolve login timeout

Fixes #123
Closes #456
Relates to #789
```

### Co-autores
```
feat(search): implement full-text search

Co-authored-by: Jane Doe <jane@example.com>
```

## Configuración de Git Template

Crear un template para commits consistentes:

```bash
# Crear template
echo "# <tipo>[alcance]: <descripción>
#
# Tipos: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
# Alcance: componente afectado (opcional)
# Descripción: presente imperativo, sin mayúscula inicial, sin punto final
#
# [Cuerpo opcional]
#
# [Pie opcional]" > ~/.gitmessage

# Configurar Git para usar el template
git config --global commit.template ~/.gitmessage
```

## Herramientas de Automatización

### Commitizen
```bash
npm install -g commitizen cz-conventional-changelog
echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc
```

### Conventional Changelog
```bash
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s
```

### Git Hooks
```bash
# .gitmessage-hook.sh
#!/bin/sh
commit_regex='^(feat|fix|docs|style|refactor|test|chore|perf|ci|build|revert)(\(.+\))?: .{1,50}'

if ! grep -qE "$commit_regex" "$1"; then
    echo "Invalid commit message format!"
    echo "Use: <type>[scope]: <description>"
    exit 1
fi
```