Compatibilidade: o que uma versão promete
Uma atualização do Aggrega pode alterar várias superfícies sobre as quais se constrói: os esquemas segundo os quais os documentos são escritos, os comandos e as opções que os scripts invocam, as ferramentas que um assistente de IA invoca, os códigos de erro que se registam e os kits de plugin com que se constrói um plugin. Esta página indica, para cada uma delas, o que uma versão pode alterar e o que não altera. Uma superfície que esta página não nomeia não traz qualquer promessa além do que a sua própria página de referência indica. A última secção indica onde uma versão comunica que uma delas mudou. As promessas desta página aplicam-se a partir da versão 0.9.0. As Releases anteriores à versão 0.9.0 não têm suporte: o registo do hub, hub.aggrega.ai, não disponibiliza qualquer versão de Plugin feita para elas, e os respetivos compiladores não conseguem ler o catálogo desse registo, cujos documentos declaram aggrega.ai/v1beta1.
O Aggrega é lançado em versões 0.x.y: uma versão de correção incrementa o último número, uma versão menor o do meio. A própria metadata.version de uma entidade do catálogo é uma questão à parte — é o seu autor que a escolhe, segundo os critérios de incremento de versão que aggrega lint --pre-publish verifica, e Resolução de versões descreve como uma referência seleciona uma delas.
Esquemas
Cada esquema que o Aggrega publica pertence a uma versão de API, aggrega.ai/v1beta1 — o valor que um documento de entidade declara no seu apiVersion. A regra abaixo abrange cada um deles: os tipos de entidade, as cargas úteis dos plugins e os esquemas do espaço de trabalho e os restantes — a IR, a configuração do espaço de trabalho, os ficheiros de bloqueio e o resto —, todos listados na Referência de esquemas. A versão de API é independente do número da versão: muitas versões leem a mesma versão de API.
O que pode mudar dentro de v1beta1
Dentro de uma versão de API, um esquema muda apenas de forma aditiva, tal como o Kubernetes altera as suas próprias versões de API. Uma versão pode:
- alterar uma descrição;
- adicionar um campo, quando o campo é opcional.
Todo o documento que era válido antes de uma alteração deste tipo continua válido depois dela e tem o mesmo significado. Um programa que lê um documento escrito pelo compilador, como a IR ou um ficheiro de bloqueio, tem de aceitar um campo que não conhece, porque um campo opcional adicionado pode aparecer nessa saída dentro de v1beta1.
O que exige v1beta2
Cada uma destas alterações exige uma nova versão de API, aggrega.ai/v1beta2:
- remover ou mudar o nome de um campo;
- tornar um campo obrigatório;
- restringir um tipo, ou o conjunto de valores que um campo aceita;
- alterar o que um valor significa.
Uma nova versão de API é uma alteração incompatível, planeada e anunciada como tal na versão que a introduz.
Um novo campo opcional chega a um catálogo com o compilador que o conhece
O compilador recusa um campo que o seu esquema não declara. É esse rigor que deteta uma chave mal escrita, e tem uma consequência que um leitor não adivinharia: uma entidade do catálogo só pode começar a usar um campo opcional acabado de adicionar numa versão que inclua um compilador que conheça esse campo.
Por exemplo, suponha-se que uma versão adiciona um campo opcional ao esquema do Component — chame-se-lhe spec.newField:
- Todo o Component escrito antes dessa versão continua válido; nenhum deles define o campo.
- Um autor de catálogo publica uma nova versão de um Component que define
spec.newField. - Um compilador dessa versão, ou de uma posterior, valida e constrói o Component.
- Um compilador de uma versão anterior recusa-o, porque o seu próprio esquema não declara o campo: a validação comunica
spec.newField: unexpected propertye indica a linha.
Assim, quem constrói com base nessa versão do catálogo atualiza primeiro para a versão que adicionou o campo, e um catálogo só publica uma entidade que use o campo depois de essa versão ter saído. A forma como uma Release bloqueada mantém as versões que resolveu está descrita em Resolução de versões.
A linha de comandos e as ferramentas do assistente
Scripts, pipelines de CI e configurações de assistentes invocam pelo nome os comandos aggrega, as opções e as ferramentas do assistente. Nas versões 0.x:
- Uma versão de correção nunca remove nem muda o nome de um comando, de uma opção ou de uma ferramenta do assistente.
- Uma versão menor pode remover ou mudar o nome de um deles, e o seu registo de alterações indica-o em Removed ou Changed.
- As adições — um novo comando, opção ou ferramenta — podem surgir em qualquer versão.
As ferramentas do assistente são as ferramentas que aggrega mcp oferece a um assistente ligado. A resposta do próprio servidor é a sua lista completa, e O que o seu assistente pode fazer com o Aggrega explica como a pedir. Uma ferramenta que executa um comando recebe o nome a partir do caminho de invocação do comando, pelo que mudar o nome de um comando muda o nome da sua ferramenta. A Visão geral da CLI lista todos os comandos.
Códigos de erro
Cada condição de paragem tem um código curto — a letra E e quatro dígitos, como em [DEVELOPER_ERROR E0007] — impresso no início do seu diagnóstico. Os códigos curtos são um contrato público: um código é atribuído uma única vez, nunca é renumerado e nunca é dado a uma condição diferente. O código de uma condição retirada permanece retirado, pelo que um código registado num runbook, numa regra de CI ou numa issue identifica a mesma condição após cada atualização.
Sentinelas de erro explica os identificadores que uma condição tem — o código curto que uma pessoa cita, o código descritivo que um programa regista e o acessor Go com que um programa compara —, o que cada um promete e como se impede que um número retirado volte a ser atribuído. A sua tabela de todas as condições resolve cada código curto, incluindo os retirados, e aggrega explain resolve um deles no terminal.
Kits de Plugin
Os kits de desenvolvimento de plugins — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust e @aggrega-ai/aggrega-pdk-typescript — e os codecs aggrega-abi que estes reexportam seguem o versionamento semântico a partir de 0.9.0. As três linguagens dos kits partilham um número de versão, e as três linguagens dos codecs partilham outro.
- Um plugin construído com base numa versão continua a ser construído com base em todas as versões posteriores da mesma linha. Dentro de
0.9.x, uma versão pode adicionar funções, tipos e constantes exportados, e nunca remove nem altera nenhum deles. - Uma alteração incompatível numa API exportada só é distribuída numa nova versão menor (de
0.9.xpara0.10.0), e uma versão de correção nunca quebra a compatibilidade. Os kits e os codecs passam para1.0.0juntamente com a própria1.0.0do Aggrega, após o que uma alteração incompatível incrementa o número principal. - Uma alteração incompatível nos codecs é uma alteração incompatível nos kits, que incrementam com ela a sua própria versão menor, porque reexportam os tipos dos codecs.
- Se um campo ou membro adicionado a um tipo existente conta como uma adição depende da linguagem. O README de cada kit, publicado com o pacote, indica o caso da sua linguagem em «Compatibility».
Esta promessa abrange a API que o código-fonte de um plugin nomeia. O que passa entre o compilador e um plugin em execução é regido, em vez disso, pela versão de ABI dos plugins: dentro de uma versão de ABI, um socket ganha apenas descrições e campos opcionais, pelo que um plugin construído com base nela continua a ser carregado. O contrato dos plugins descreve os sockets, e o guia do programador de plugins, o fluxo de trabalho em torno deles.
O que diz o registo de alterações de uma versão
As notas de cada versão, na página de versões, incluem o seu registo de alterações, agrupado sob títulos como Added, Changed, Removed e Fixed. Para as superfícies desta página:
- Um comando, uma opção ou uma ferramenta do assistente removidos ou com o nome alterado são listados em Removed ou Changed, na versão menor que faz a alteração.
- Uma nova versão de API de esquema é anunciada como alteração incompatível na versão que a introduz.
- Uma alteração incompatível nos kits de plugin ou nos codecs é visível no seu número de versão: é uma nova versão menor abaixo de
1.0.0. - Um código de erro nunca muda de significado, pelo que nenhuma versão tem um a anunciar.