0018. Estrategia general de versionado

Fecha: 2026-09-08 Estado: Propuesto Módulo(s) afectado(s): transversal, API, móvil, web y escritorio

Contexto

Versionar no es asignar un número a cada despliegue: es comunicar a quienes consumen un componente qué pueden esperar al actualizarlo. Sin una regla común, un cambio pequeño puede romper una integración, obligar a actualizar una app sin aviso o dejar versiones antiguas sin una fecha clara de retiro.

Esta decisión define por qué, cuándo y cómo se versionan los componentes del ecosistema. El detalle del contrato REST y de su validación en CI se encuentra en los ADR 0016 y 0017, respectivamente.

Decisión

Se adopta Versionado Semántico (SemVer) para las versiones publicadas de aplicaciones, librerías y contratos:

MAJOR.MINOR.PATCH
  2  .  4  .  1

La versión describe el impacto para el consumidor, no el tamaño del cambio ni el número de tickets incluidos. Todo componente público comienza en 1.0.0; 0.x.y queda reservado para prototipos que aún no tengan consumidores ni compromiso de compatibilidad.

Por qué versionamos

• Proteger a los consumidores: permite saber si actualizar puede requerir cambios en código, configuración o datos.
• Desplegar con control: hace posible identificar rápidamente qué artefacto está en producción y volver a uno anterior si es necesario.
• Planificar migraciones: una versión mayor nueva crea un periodo explícito de convivencia, comunicación y retiro de la versión anterior.
• Tener trazabilidad: incidentes, notas de entrega, binarios y contratos se pueden relacionar con una versión concreta.

Cuándo incrementar la versión

Cambio realizado	Incremento	Ejemplos
Rompe un uso documentado o exige una migración	MAJOR	eliminar o renombrar endpoint/campo público; cambiar un tipo; requerir un campo antes opcional; retirar una funcionalidad; cambiar comportamiento esperado por clientes
Añade capacidad compatible	MINOR	endpoint nuevo; campo opcional en una respuesta; pantalla o función nueva; permiso o configuración opcional nuevos
Corrige sin alterar el contrato	PATCH	corrección de cálculo, seguridad o rendimiento; ajuste visual; mensaje de error más claro; corrección interna
Solo cambia implementación o documentación	sin incremento público obligatorio	refactor interno, pruebas, CI, documentación; se publica una nueva compilación solo si el proceso de despliegue lo requiere

Ante la duda, se evalúa desde el punto de vista del consumidor: si una integración que funcionaba con la versión anterior puede fallar o necesita cambios, es un MAJOR. No se usa un PATCH para introducir una ruptura con el fin de evitar una versión mayor.

Cómo versionar por tipo de componente

APIs REST

• Toda API se expone bajo /api/v<major>/, por ejemplo /api/v1/pedidos y /api/v2/pedidos.
• La versión en la ruta cambia solo ante cambios rompedores del contrato. Los cambios MINOR y PATCH permanecen en la misma ruta mientras sean compatibles hacia atrás.
• El documento OpenAPI publica la versión del contrato y se verifica en CI. Los criterios concretos y los contract tests son los de los ADR 0016 y 0017.

Ejemplo: añadir observaciones opcional a GET /api/v1/pedidos/{id} es compatible y mantiene v1. Renombrar cantidad a cantidad_facturable requiere publicar /api/v2/... y mantener v1 durante la migración.

Aplicaciones móviles y de escritorio

• El binario se etiqueta con SemVer y se registra también un número de build ascendente para las tiendas o la distribución interna.
• Antes de una versión MAJOR, se publican instrucciones de migración y se define la versión mínima soportada por el backend.
• La aplicación consulta al inicio una política de versión mínima. Se usa actualización obligatoria únicamente cuando una versión antigua presenta un riesgo de seguridad, corrupción de datos o ya no puede comunicarse con una API soportada. Para nuevas funcionalidades compatibles se prefiere la actualización recomendada, no el bloqueo.

Aplicaciones web

• Cada artefacto desplegable lleva SemVer, etiqueta Git y notas de entrega, aunque el usuario reciba la actualización automáticamente.
• Un despliegue debe conservar la posibilidad de rollback al artefacto anterior. Si el frontend y una API cambian de forma incompatible, primero se publica la API nueva y se mantiene la anterior durante la transición.
• Los cambios visibles pero compatibles son MINOR; las correcciones son PATCH. Un MAJOR aplica cuando cambia una integración, una configuración pública o una experiencia que requiere migración explícita de clientes administrados.

Librerías, SDK y paquetes compartidos

• Se publica una nueva versión para todo cambio disponible a otros proyectos.
• El rango de dependencias debe permitir PATCH/MINOR compatibles según el gestor usado, pero no actualizar automáticamente un MAJOR.
• Una API marcada como obsoleta sigue disponible al menos durante un MINOR antes de eliminarse en el siguiente MAJOR, salvo una corrección urgente de seguridad.

Proceso de publicación

1. Clasificar el cambio con la tabla anterior antes de fusionarlo. Si hay consumidores externos o dudas de compatibilidad, se trata como rompedor hasta demostrar lo contrario.
2. Actualizar la versión y las notas de entrega. Las notas indican qué cambió, quién debe actuar y, en un MAJOR, los pasos y fecha límite de migración.
3. Validar. CI ejecuta pruebas, análisis de compatibilidad del contrato y la compilación de consumidores relevantes. Un cambio rompedor en una API existente no puede pasar como v1 (ADR 0017).
4. Etiquetar y publicar el artefacto. La etiqueta Git, el paquete/binario, el despliegue y las notas deben usar la misma versión, por ejemplo v2.4.1.
5. Deprecar y retirar cuando corresponda. La versión anterior se marca como deprecada, se comunica a sus consumidores y se monitoriza su uso antes de apagarla.

Convivencia y deprecación de versiones MAJOR

Publicar v2 no autoriza a eliminar v1 inmediatamente. El responsable del componente debe definir y comunicar antes del lanzamiento:

• consumidores afectados y ruta de migración;
• fecha de deprecación y fecha estimada de retiro;
• periodo de convivencia, como mínimo dos ciclos de release cuando el riesgo no exija otra medida;
• métricas o registros que permitan confirmar que los consumidores dejaron de utilizar la versión anterior.

Una excepción por vulnerabilidad crítica puede retirar o bloquear una versión antes del periodo previsto. Debe documentarse el motivo, comunicar la acción y ofrecer la actualización segura disponible.

Alternativas descartadas

• Versionado por fechas: ordena lanzamientos, pero no comunica si existe compatibilidad ni el esfuerzo de actualización.
• Una sola versión para todo el monorepo: convierte cambios independientes en releases innecesarios y oculta qué componente cambió realmente.
• API sin versión en la ruta o solo por cabecera: dificulta la coexistencia, los cachés, los logs y las pruebas de contrato.
• Forzar todas las actualizaciones de cliente: aumenta el abandono y no es necesario para cambios compatibles; se reserva para los casos definidos.

Consecuencias

• Cada release comunica de forma consistente el riesgo de actualizar y deja evidencia trazable para soporte y auditoría.
• Las versiones MAJOR requieren planificación adicional: compatibilidad, migración, comunicación y retiro controlado.
• Mantener compatibilidad implica más de una versión temporalmente, pero evita interrupciones masivas y desplaza las migraciones a un proceso predecible.
• Producto, desarrollo y soporte deben conocer la política de soporte de cada versión publicada.