Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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:

  1. Todo o Component escrito antes dessa versão continua válido; nenhum deles define o campo.
  2. Um autor de catálogo publica uma nova versão de um Component que define spec.newField.
  3. Um compilador dessa versão, ou de uma posterior, valida e constrói o Component.
  4. 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 property e 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.x para 0.10.0), e uma versão de correção nunca quebra a compatibilidade. Os kits e os codecs passam para 1.0.0 juntamente com a própria 1.0.0 do 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.