sf-sim/CONTRIBUTING.md

# Guía de Contribución

¡Gracias por tu interés en contribuir a este proyecto! Este documento establece las pautas para asegurar que nuestro código se mantenga de alta calidad y que nuestra historia de git sea limpia y legible.

## 1. Flujo de Trabajo con Git

### Ramas (Branches)

Utilizamos un modelo de ramas basado en el propósito del cambio.

- **Rama Principal**: `main`. Esta rama siempre debe ser estable y desplegable.
- **Creación de Ramas**: Crea una nueva rama para cada tarea, feature o bugfix. Nunca trabajes directamente sobre `main`.

#### Convención de nombres de ramas

- **Con ticket:** `WEBINT-XXX_descripcion-breve` — el ticket actúa como tipo.
- **Sin ticket:** `tipo/descripcion-breve`

Donde `tipo` puede ser:

- `feat`: Nuevas características o funcionalidades.
- `fix`: Corrección de errores.
- `docs`: Cambios solo en documentación.
- `style`: Cambios que no afectan el significado del código (espacios, formato, etc).
- `refactor`: Cambio de código que no arregla un bug ni añade una característica.
- `test`: Añadir tests faltantes o corregir existentes.
- `chore`: Cambios en el proceso de construcción o herramientas auxiliares.

Ejemplos:

- `WEBINT-338_tiempo_suspension`
- `feat/gateway-francia`
- `fix/correlation-id`

### Commits

Seguimos la convención de **Conventional Commits** para nuestros mensajes de commit. Esto ayuda a generar changelogs automáticos y facilita la lectura del historial.

#### Formato

```text
tipo(alcance): descripción breve en imperativo

[Cuerpo opcional: descripción más detallada del cambio]

[Pie opcional: referencias a issues, breaking changes]
```

#### Tipos comunes

- `feat`: Una nueva característica.
- `fix`: Una corrección de un bug.
- `docs`: Cambios en la documentación.
- `style`: Formato, puntos y comas faltantes, etc. (no cambios en la lógica).
- `refactor`: Refactorización de código en producción.
- `perf`: Cambio de código que mejora el rendimiento.
- `test`: Añadir o corregir tests.
- `chore`: Tareas rutinarias, actualizaciones de dependencias, etc.

Ejemplos:

- `feat(auth): implementar login con Google`
- `fix(db): corregir error de conexión en timeout`
- `docs(readme): actualizar instrucciones de instalación`

### Pull Requests (PRs)

1. Asegúrate de que tu rama está actualizada con `main`.
2. Abre un Pull Request dando una descripción clara de los cambios.
3. Enlaza cualquier Issue relacionado (ej. `Closes #123`).
4. Asigna como revisor a **Alvar San Martin** (`alvarsanmartin@savefamilygps.com`) y espera su aprobación antes de fusionar.

## 2. Estilo de Código

Las convenciones de código (naming, idioma, TypeScript, tests) están en:

- [`.claude/rules/code-style.md`](.claude/rules/code-style.md) — reglas resumidas que aplican a cualquier cambio.
- [`.agents/skills/sf-backend-architecture/references/CODE-STYLE.md`](.agents/skills/sf-backend-architecture/references/CODE-STYLE.md) — detalle completo con ejemplos y justificaciones.
- [`.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md`](.agents/skills/sf-backend-architecture/references/HOUSE-STYLE.md) — convenciones de arquitectura (capas DDD, ports, Result, ESM).

## 3. Tests

Estrategia detallada en `HOUSE-STYLE.md` § Tests (vitest, tres niveles: domain puro / application con mocks de ports / infrastructure contra BD o testcontainers).

### Política por defecto (TDD)

- **Código nuevo:** se escribe con TDD (test primero) e incluye tests del nivel apropiado (domain puro si aplica; application con mocks; infrastructure si se añade un adapter).
- **Cobertura mínima del repo:** 70%. Cada PR debe mantener o aumentar la cobertura.
- **Bugs corregidos:** requieren al menos un test de regresión que reproduzca el fallo.
- **Antes de abrir un PR:** los tests existentes deben pasar (`yarn vitest run` o `/check`).

### Excepción para este repo (sf-sim)

sf-sim es legacy con cobertura actual ~12%. La regla TDD + 70% es **aspiracional, no bloqueante**:

- Estricta para código nuevo (sí debe llevar tests).
- Al tocar código legacy sin tests, retrofittearlos es opcional pero se valora positivamente. Nada de retrofits masivos.
- La excepción decae cuando el repo alcance el 70% global.

> Al reutilizar estos ficheros de configuración en un repo nuevo, esta excepción no aplica — la política por defecto es la que rige.

---

Equipo de Desarrollo.