Versionado y changelog
Versionado de API
Sección titulada «Versionado de API»La versión mayor forma parte de la ruta contractual. Dentro de una versión pueden añadirse cambios que no alteren el significado ni obliguen a cambiar un consumidor existente, por ejemplo:
- campos opcionales en respuestas;
- nuevas operaciones;
- metadatos adicionales.
Los requests son estrictos: un campo desconocido se rechaza para no ocultar errores ortográficos. En respuestas, errores y payloads de un tipo de evento conocido, el SDK oficial valida los campos publicados y preserva campos adicionales.
Enumeraciones y eventos no son una adición trivial
Sección titulada «Enumeraciones y eventos no son una adición trivial»Agregar un valor a una enumeración cerrada o un nuevo event.type puede romper un switch
exhaustivo. Por eso no se clasifica automáticamente como compatible:
- una operación nueva o un campo opcional puede publicarse en una versión menor del SDK;
- un valor nuevo detrás de una capacidad explícita requiere changelog y una actualización coordinada;
- si el valor debe llegar a integraciones existentes o expande una unión cerrada, se usa una migración explícita o una nueva versión mayor.
El verificador del SDK acepta campos adicionales en eventos conocidos, pero rechaza un tipo de evento desconocido. No trates como exitoso un estado o evento que tu integración no comprende.
Cambios incompatibles
Sección titulada «Cambios incompatibles»Requieren nueva versión mayor o una migración explícita:
- eliminar o renombrar campos;
- cambiar tipos o significado;
- hacer requerido un campo antes opcional;
- cambiar autenticación o firma;
- alterar reglas de idempotencia;
- reutilizar códigos con otra semántica.
También se considera incompatible introducir sin coordinación un valor nuevo en una enumeración o unión discriminada que los consumidores procesan exhaustivamente.
Changelog
Sección titulada «Changelog»Cada entrada debe indicar:
- fecha efectiva;
- ambiente;
- operaciones o esquemas afectados;
- clasificación compatible o incompatible;
- acción requerida;
- fecha de deprecación o retiro;
- enlace a la guía de migración.
Política de deprecación
Sección titulada «Política de deprecación»Una deprecación visible no es un retiro inmediato. CierreListo debe comunicar:
- alternativa recomendada;
- ventana de convivencia;
- métricas de uso afectado;
- recordatorios;
- fecha de retiro;
- resultado posterior.
Control de contrato
Sección titulada «Control de contrato»CI regenera OpenAPI y falla si el archivo versionado cambia sin actualizarse. También compila y prueba el SDK, instala su tarball en un consumidor TypeScript externo y valida el portal Astro contra el contrato generado.
La revisión humana del changelog sigue siendo necesaria para clasificar compatibilidad semántica: un diff válido de OpenAPI no demuestra por sí solo que un cambio sea compatible.