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

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 — reglas resumidas que aplican a cualquier cambio.
• .agents/skills/sf-backend-architecture/references/CODE-STYLE.md — detalle completo con ejemplos y justificaciones.
• .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.