Compatibilidad: lo que promete una versión
Una actualización de Aggrega puede cambiar varias superficies sobre las que construyes: los esquemas con los que se escriben tus documentos, los comandos y opciones que llaman tus scripts, las herramientas que llama un asistente de IA, los códigos de error que registras y los kits de plugins con los que se construye un plugin. Esta página indica, para cada una de ellas, lo que una versión puede cambiar y lo que no. Una superficie que esta página no nombra no conlleva ninguna promesa más allá de lo que indica su propia página de referencia. La última sección indica dónde te comunica una versión que una de ellas ha cambiado. Las promesas de esta página rigen a partir de la versión 0.9.0. Las Releases anteriores a la versión 0.9.0 no tienen soporte: el registro del hub, hub.aggrega.ai, no ofrece ninguna versión de Plugin hecha para ellas, y sus compiladores no pueden leer el catálogo de ese registro, cuyos documentos declaran aggrega.ai/v1beta1.
Aggrega se publica en versiones 0.x.y: una versión de parche incrementa el último número, una versión menor el del medio. La propia metadata.version de una entidad del catálogo es un asunto aparte — la elige su autor, según los criterios de incremento de versión que comprueba aggrega lint --pre-publish, y Resolución de versiones describe cómo una referencia selecciona una.
Esquemas
Cada esquema que publica Aggrega pertenece a una versión de API, aggrega.ai/v1beta1 — el valor que un documento de entidad declara en su apiVersion. La regla siguiente se aplica a cada uno de ellos: los tipos de entidad, las cargas útiles de los plugins y los esquemas del espacio de trabajo y demás — la IR, la configuración del espacio de trabajo, los archivos de bloqueo y el resto —, todos enumerados en la Referencia de esquemas. La versión de API es independiente del número de versión: muchas versiones leen la misma versión de API.
Qué puede cambiar dentro de v1beta1
Dentro de una versión de API, un esquema solo cambia de forma aditiva, como Kubernetes cambia sus propias versiones de API. Una versión puede:
- cambiar una descripción;
- añadir un campo, cuando el campo es opcional.
Todo documento que era válido antes de un cambio así sigue siendo válido después y significa lo mismo. Un programa que lee un documento que escribe el compilador, como la IR o un archivo de bloqueo, debe aceptar un campo que no conoce, porque un campo opcional añadido puede aparecer en esa salida dentro de v1beta1.
Qué requiere v1beta2
Cada uno de estos cambios requiere una nueva versión de API, aggrega.ai/v1beta2:
- eliminar o renombrar un campo;
- hacer obligatorio un campo;
- restringir un tipo, o el conjunto de valores que acepta un campo;
- cambiar lo que significa un valor.
Una nueva versión de API es un cambio incompatible, programado y anunciado como tal en la versión que lo introduce.
Un nuevo campo opcional llega a un catálogo con el compilador que lo conoce
El compilador rechaza un campo que su esquema no declara. Ese rigor es lo que detecta una clave mal escrita, y tiene una consecuencia que un lector no adivinaría: una entidad del catálogo puede empezar a usar un campo opcional recién añadido solo en una versión que incluya un compilador que conozca ese campo.
Por ejemplo, supongamos que una versión añade un campo opcional al esquema de Component — llamémoslo spec.newField:
- Todo Component escrito antes de esa versión sigue siendo válido; ninguno de ellos establece el campo.
- Un autor de catálogo publica una nueva versión de un Component que establece
spec.newField. - Un compilador de esa versión, o de una posterior, valida y construye el Component.
- Un compilador de una versión anterior lo rechaza, porque su propio esquema no declara el campo: la validación informa
spec.newField: unexpected propertye indica la línea.
Así que quien construye contra esa versión del catálogo actualiza primero a la versión que añadió el campo, y un catálogo publica una entidad que usa el campo solo cuando esa versión ya ha salido. Cómo una Release bloqueada conserva las versiones que resolvió se explica en Resolución de versiones.
La línea de comandos y las herramientas del asistente
Los scripts, los pipelines de CI y las configuraciones de asistentes llaman por su nombre a los comandos aggrega, las opciones y las herramientas del asistente. En las versiones 0.x:
- Una versión de parche nunca elimina ni renombra un comando, una opción o una herramienta del asistente.
- Una versión menor puede eliminar o renombrar alguno, y su registro de cambios lo indica en Removed o Changed.
- Las adiciones — un nuevo comando, opción o herramienta — pueden llegar en cualquier versión.
Las herramientas del asistente son las herramientas que aggrega mcp ofrece a un asistente conectado. La propia respuesta del servidor es su lista completa, y Lo que tu asistente puede hacer con Aggrega explica cómo pedirla. Una herramienta que ejecuta un comando toma su nombre de la ruta de invocación del comando, de modo que renombrar un comando renombra su herramienta. La Descripción general de la CLI enumera todos los comandos.
Códigos de error
Toda condición de detención lleva un código corto — la letra E y cuatro dígitos, como en [DEVELOPER_ERROR E0007] — que se imprime al principio de su diagnóstico. Los códigos cortos son un contrato público: un código se asigna una sola vez, nunca se renumera y nunca se da a una condición distinta. El código de una condición retirada permanece retirado, de modo que un código registrado en un runbook, una regla de CI o una incidencia designa la misma condición tras cada actualización.
Centinelas de error explica los identificadores que lleva una condición — el código corto que cita una persona, el código descriptivo que registra un programa y el accesor de Go con el que compara un programa —, lo que promete cada uno y cómo se evita que un número retirado se vuelva a asignar. Su tabla de todas las condiciones resuelve cada código corto, incluidos los retirados, y aggrega explain resuelve uno en el terminal.
Kits de Plugin
Los kits de desarrollo de plugins — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust y @aggrega-ai/aggrega-pdk-typescript — y los códecs aggrega-abi que reexportan siguen el versionado semántico a partir de 0.9.0. Los tres lenguajes de los kits comparten un número de versión, y los tres lenguajes de los códecs comparten otro.
- Un plugin construido contra una versión sigue construyéndose contra cada versión posterior de la misma línea. Dentro de
0.9.x, una versión puede añadir funciones, tipos y constantes exportados, y nunca elimina ni cambia ninguno. - Un cambio incompatible en una API exportada solo se publica en una nueva versión menor (de
0.9.xa0.10.0), y una versión de parche nunca rompe la compatibilidad. Los kits y los códecs pasan a1.0.0junto con la propia1.0.0de Aggrega, tras lo cual un cambio incompatible incrementa el número mayor. - Un cambio incompatible en los códecs es un cambio incompatible en los kits, que incrementan con él su propia versión menor, porque reexportan los tipos de los códecs.
- Si un campo o miembro añadido a un tipo existente cuenta como una adición depende del lenguaje. El README de cada kit, publicado con el paquete, indica el caso de su lenguaje en «Compatibility».
Esta promesa cubre la API que nombra el código fuente de un plugin. Lo que pasa entre el compilador y un plugin en ejecución lo garantiza en cambio la versión de ABI de los plugins: dentro de una versión de ABI, un socket solo gana descripciones y campos opcionales, de modo que un plugin construido contra ella sigue cargándose. El contrato de plugins describe los sockets, y la guía para desarrolladores de plugins, el flujo de trabajo en torno a ellos.
Lo que dice el registro de cambios de una versión
Las notas de cada versión, en la página de versiones, incluyen su registro de cambios, agrupado bajo encabezados como Added, Changed, Removed y Fixed. Para las superficies de esta página:
- Un comando, una opción o una herramienta del asistente eliminados o renombrados se indican en Removed o Changed, en la versión menor que hace el cambio.
- Una nueva versión de API de esquema se anuncia como cambio incompatible en la versión que la introduce.
- Un cambio incompatible en los kits de plugins o en los códecs se refleja en su número de versión: es una nueva versión menor por debajo de
1.0.0. - Un código de error nunca cambia de significado, así que ninguna versión tiene uno que anunciar.