Saltar al contenido principal

Política de compatibilidad

A partir de la versión 1.0.0, Canopy se compromete a mantener una compatibilidad hacia atrás documentada dentro de una línea de versión mayor. Esta página es el contrato: describe qué permanece estable, qué puede cambiar y cómo funcionan las deprecaciones, para que los operadores puedan planificar las actualizaciones sin sorpresas.

La política se aplica a 1.x. Una futura línea 2.x podría revisarla; de ser así, una guía de migración se publicará junto con las notas de lanzamiento de 2.0.0.

Qué está cubierto​

Esquema de base de datos (migraciones Alembic)​

Dentro de 1.x:

  • Las migraciones son aditivas o compatibles hacia atrás en la actualización.
  • Se pueden añadir nuevas columnas en cualquier momento.
  • Las columnas existentes no se eliminarán sin pasar por un ciclo de deprecación.
  • Las columnas existentes no se renombrarán sin un ciclo de deprecación (un renombrado se implementa como añadir-nueva-columna → relleno → deprecar-columna-antigua → eliminar-en-siguiente-mayor).
  • Los cambios de tipo se limitan a ampliaciones (por ejemplo, varchar(80) → varchar(255)); los cambios de reducción pasan por deprecación.
  • Las restricciones de clave foránea no se volverán más estrictas (por ejemplo, ON DELETE SET NULL convirtiéndose en ON DELETE CASCADE) sin un ciclo de deprecación.

Los operadores pueden actualizar con confianza; la auto-migración al iniciar el backend es segura de ejecutar sobre datos de producción.

Metamodelo integrado​

Dentro de 1.x, el metamodelo que se incluye en backend/app/services/seed.py es estable:

  • Las claves de tipos de tarjeta integrados (Application, Initiative, BusinessCapability, etc.) no se renombrarán ni eliminarán.
  • Las claves de campo integradas en esos tipos no se eliminarán sin un ciclo de deprecación.
  • Las claves de tipos de relación integrados no se renombrarán ni eliminarán sin un ciclo de deprecación.
  • Los subtipos predeterminados incluidos con los tipos integrados son estables.

Las personalizaciones propias de los operadores (tipos de tarjeta personalizados, campos personalizados añadidos a través de la interfaz de administración, tipos de relación personalizados) son propiedad del operador y no están cubiertas por esta política.

API REST (/api/v1/)​

Dentro de 1.x:

  • Los endpoints bajo /api/v1/ no se eliminarán sin un ciclo de deprecación.
  • Los nombres de campos existentes en solicitudes y respuestas no se renombrarán sin un ciclo de deprecación.
  • Los tipos de campo no cambiarán de forma incompatible (por ejemplo, cadena → array).
  • Los nuevos campos de solicitud opcionales y los nuevos campos de respuesta no son cambios incompatibles y pueden aparecer en cualquier versión menor.
  • Los nuevos endpoints no son cambios incompatibles y pueden aparecer en cualquier versión menor.
  • La semántica de autenticación (JWT Bearer, la forma del contenido de /auth/login) es estable.
  • La semántica de los códigos de estado HTTP es estable para las rutas de éxito y error documentadas.

El comportamiento más allá de la superficie documentada (cabeceras no documentadas, el texto de los mensajes de error internos, el ordenamiento cuando no se especifica sort_by) no está cubierto.

Claves de permiso​

Las claves de permiso definidas en backend/app/core/permissions.py son estables dentro de 1.x. Se pueden añadir nuevas claves; las claves existentes no se renombrarán ni eliminarán sin un ciclo de deprecación.

El conjunto de permisos concedidos por defecto a los roles sembrados (admin, bpm_admin, member, viewer) puede cambiar entre versiones menores, con una nota en el CHANGELOG. Los operadores que han personalizado los permisos de roles en su despliegue no se ven afectados.

Configuración (variables de entorno)​

Las variables de entorno existentes documentadas en CLAUDE.md y README.md son estables dentro de 1.x. Se pueden añadir nuevas variables con valores predeterminados razonables. Los valores predeterminados pueden cambiar con una nota en el CHANGELOG cuando el cambio sea relevante para el operador (por ejemplo, un nuevo puerto predeterminado).

Secretos cifrados en reposo​

El marcador de prefijo enc: y la clave derivada de Fernet en backend/app/core/encryption.py son estables dentro de 1.x. Los operadores no necesitan volver a cifrar los secretos entre actualizaciones menores.

Ciclo de deprecación​

Cuando algo cubierto por esta política necesita eliminarse:

  1. Marcar como deprecado en la versión menor N. La entrada del CHANGELOG incluye una sección Deprecated que describe el cambio. Para los endpoints de la API, la ruta deprecada emite una cabecera de respuesta Deprecation: true (RFC 8594) y una cabecera Sunset que indica el objetivo de eliminación más temprano.
  2. Continuar admitiendo en la versión menor N+1. La eliminación no puede ocurrir en la misma versión menor que la deprecación. La forma deprecada sigue funcionando.
  3. Eliminación más temprana en la versión menor N+2 o en 2.0 (lo que llegue antes). La eliminación aparece con una sección Removed en el CHANGELOG y una nota de migración.

Para los cambios en la forma de los datos (migraciones Alembic), se aplica la misma cadencia N → N+1, expresada como añadir-nuevo → rellenar → eliminar-antiguo.

Qué no está cubierto​

Esto está explícitamente fuera del alcance y puede cambiar en cualquier momento:

  • La estructura interna de módulos Python bajo backend/app/. Las importaciones de app.models, app.services, etc. no forman parte de la API pública. Los plugins o scripts que dependan de importaciones internas deben fijar una versión específica de Canopy.
  • La estructura de los blobs JSONB almacenados en tablas integradas (fields_schema, section_config, attributes, lifecycle) más allá de lo que lee la API REST documentada. La forma JSON en disco puede evolucionar para admitir nuevas funcionalidades.
  • Componentes internos del frontend: rutas de archivos de componentes, firmas de propiedades de componentes en frontend/src/, el contenido de frontend/src/types/index.ts y el estilo de los componentes MUI. Los operadores que usan el frontend incluido están protegidos; quienes incrustan componentes del árbol fuente lo hacen bajo su propia responsabilidad.
  • Personalizaciones del metamodelo introducidas por el operador. Si añade un tipo de tarjeta o campo personalizado a través de la interfaz de administración, usted es responsable de la historia de migración cuando lo cambie.
  • Datos de demostración y siembra (SEED_DEMO=true). El conjunto de datos de demostración puede evolucionar libremente entre lanzamientos.
  • Servicios de terceros incluidos: la versión de DrawIO, la imagen Ollama incluida, la versión de swagger-ui-dist incrustada. Estos pueden actualizarse en cualquier momento.
  • Comportamiento con configuraciones no predeterminadas que están marcadas explícitamente como experimentales en las entradas del CHANGELOG.

Qué cambia realmente con «1.0.0»​

En comparación con la serie 0.x, 1.0.0 en sí mismo no es una versión de funcionalidades — es el punto a partir del cual empiezan a aplicarse los compromisos anteriores. El código que se publica en 1.0.0 es el mismo que se publicó en 0.71.0, más el refuerzo de la cadena de suministro y los cambios en el flujo de colaboradores documentados en la entrada del CHANGELOG de 1.0.0.

Las versiones anteriores a 1.0 no estaban cubiertas por esta política. Las migraciones entre versiones 0.x podían incluir y de hecho incluían eliminaciones de esquemas, renombrados y cambios incompatibles en el metamodelo. A partir de 1.0.0, estos cambios pasan por el ciclo de deprecación.