Release Notes y Changelog API

Este documento define el formato obligatorio para publicar cambios técnicos y funcionales por release.

1. Política de changelog

• Todo release a staging o production debe generar changelog.
• El changelog debe clasificar cambios en:
  • breaking
  • non_breaking
  • fix
  • security
  • deprecated
• Si existe cambio de contrato API, el changelog debe enlazar:
  • endpoint afectado,
  • impacto esperado en cliente,
  • fecha objetivo de retiro (si aplica).

2. Template oficial de release notes

## Release YYYY.MM.DD-N

### Resumen ejecutivo
- Alcance:
- Riesgo:
- Ventana:
- Owner release:

### Cambios breaking
- [ ] Endpoint/Contrato:
- [ ] Impacto:
- [ ] Plan de migración:
- [ ] Fecha de sunset:

### Cambios non-breaking
- ...

### Fixes
- ...

### Seguridad
- ...

### Migraciones de datos
- [ ] Sí/No
- [ ] Script:
- [ ] Rollback:

### Observabilidad
- Dashboards impactados:
- Nuevas alertas:

### Verificación post-release
- Smoke tests:
- Métricas esperadas:
- Estado final:

3. Matriz de compatibilidad API

Ruta API	Estado	Compatibilidad	Sunset
/api/v1/*	Activa	Base actual	N/A
/api/v2/*	Futura	Solo cuando haya breaking aprobado	Definir

Reglas:

• No se publica breaking en v1 sin RFC aprobado.
• Todo endpoint marcado deprecated: true debe tener fecha de retiro explícita.

4. Checklist de salida de release

• Changelog publicado en PR/release tag.
• OpenAPI actualizado y versionado.
• Matriz de compatibilidad actualizada.
• Plan de rollback validado.
• Alertas y dashboards revisados 30 minutos post-release.

5. Cambio reciente de contrato (Auth)

• Fecha: 2026-02-17
• Tipo: breaking
• Alcance:
  • POST /api/v1/auth/login, POST /api/v1/auth/token/verify, POST /api/v1/auth/refresh emiten cookies HttpOnly (accessToken, refreshToken) sin exponer tokens en body.
  • POST /api/v1/auth/logout prioriza cookie accessToken y conserva fallback Authorization: Bearer.
• Impacto cliente:
  • Frontend debe enviar credenciales (credentials: include) y dejar de depender de tokens en body.
  • Integraciones legacy por bearer se mantienen solo para compatibilidad de logout.