Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia 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 você constrói: os esquemas com base nos quais seus documentos são escritos, os comandos e opções que seus scripts chamam, as ferramentas que um assistente de IA chama, os códigos de erro que você registra e os kits de plugin com os quais um plugin é construído. Esta página informa, 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 menciona não traz nenhuma promessa além do que sua própria página de referência afirma. A última seção indica onde uma versão informa que uma delas mudou. As promessas desta página valem a partir da versão 0.9.0. As Releases anteriores à versão 0.9.0 não têm suporte: o registro do hub, hub.aggrega.ai, não disponibiliza nenhuma versão de Plugin feita para elas, e os compiladores delas não conseguem ler o catálogo desse registro, cujos documentos declaram aggrega.ai/v1beta1.

O Aggrega é lançado em versões 0.x.y: uma versão de patch incrementa o último número, uma versão secundária, o do meio. A própria metadata.version de uma entidade de catálogo é uma questão à parte — seu autor 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

Todo esquema que o Aggrega publica pertence a uma versão de API, aggrega.ai/v1beta1 — o valor que um documento de entidade declara em seu apiVersion. A regra abaixo abrange cada um deles: os tipos de entidade, os payloads dos plugins e os esquemas do espaço de trabalho e os demais — a IR, a configuração do espaço de trabalho, os arquivos de bloqueio e o resto —, todos listados na Referência de esquemas. A versão de API é separada 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, como o Kubernetes muda suas próprias versões de API. Uma versão pode:

  • alterar uma descrição;
  • adicionar um campo, quando o campo é opcional.

Todo documento que era válido antes de tal alteração continua válido depois dela e significa a mesma coisa. Um programa que lê um documento escrito pelo compilador, como a IR ou um arquivo de bloqueio, precisa 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 renomear 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, agendada e anunciada como tal na versão que a introduz.

Um novo campo opcional chega a um catálogo junto com o compilador que o conhece

O compilador recusa um campo que seu esquema não declara. Esse rigor é o que detecta uma chave digitada errada, e tem uma consequência que um leitor não adivinharia: uma entidade de catálogo só pode começar a usar um campo opcional recém-adicionado em uma versão que traga um compilador que conheça esse campo.

Por exemplo, suponha que uma versão adicione um campo opcional ao esquema do Component — chame-o de spec.newField:

  1. Todo 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 o recusa, porque seu próprio esquema não declara o campo: a validação relata spec.newField: unexpected property e indica a linha.

Portanto, 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 usa o campo depois que essa versão é lançada. Como uma Release travada mantém as versões que resolveu está descrito em Resolução de versões.

A linha de comando e as ferramentas do assistente

Scripts, pipelines de CI e configurações de assistente chamam comandos aggrega, opções e ferramentas do assistente pelo nome. Nas versões 0.x:

  • Uma versão de patch nunca remove nem renomeia um comando, uma opção ou uma ferramenta do assistente.
  • Uma versão secundária pode remover ou renomear um deles, e seu registro de alterações informa isso em Removed ou Changed.
  • Adições — um novo comando, opção ou ferramenta — podem vir em qualquer versão.

As ferramentas do assistente são as ferramentas que aggrega mcp oferece a um assistente conectado. A própria resposta do servidor é a lista completa delas, e O que seu assistente pode fazer com o Aggrega explica como solicitá-la. Uma ferramenta que executa um comando recebe o nome a partir do caminho de invocação do comando, portanto renomear um comando renomeia sua ferramenta. A Visão geral da CLI lista todos os comandos.

Códigos de erro

Toda condição de interrupção traz 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 desativada permanece desativado, de modo que um código registrado em um runbook, uma regra de CI ou uma issue identifica a mesma condição após cada atualização.

Sentinelas de erro explica os identificadores que uma condição carrega — o código curto que uma pessoa cita, o código descritivo que um programa registra e o acessor Go com o qual um programa faz a correspondência —, o que cada um promete e como se impede que um número desativado seja atribuído novamente. A sua tabela de todas as condições resolve cada código curto, incluindo os desativados, 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 eles reexportam seguem o versionamento semântico a partir de 0.9.0. As três linguagens dos kits compartilham um número de versão, e as três linguagens dos codecs compartilham outro.

  • Um plugin construído com base em uma versão continua sendo 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 em uma API exportada só é lançada em uma nova versão secundária (de 0.9.x para 0.10.0), e uma versão de patch nunca quebra a compatibilidade. Os kits e os codecs passam para 1.0.0 junto com a própria 1.0.0 do Aggrega, depois do 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 sua própria versão secundária, 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, descreve o caso de sua linguagem em “Compatibility”.

Essa promessa abrange a API que o código-fonte de um plugin nomeia. O que trafega 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, de modo que um plugin construído com base nela continua sendo carregado. O contrato de plugins descreve os sockets, e o guia do desenvolvedor de plugins, o fluxo de trabalho em torno deles.

O que o registro de alterações de uma versão informa

As notas de cada versão, na página de versões, trazem seu registro 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 renomeados são listados em Removed ou Changed, na versão secundária 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 aparece no número de versão deles: é uma nova versão secundária abaixo de 1.0.0.
  • Um código de erro nunca muda de significado, portanto nenhuma versão tem um a anunciar.