Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Compatibilità: cosa promette un rilascio

Un aggiornamento di Aggrega può modificare diverse superfici su cui costruisci: gli schemi su cui sono scritti i tuoi documenti, i comandi e i flag che i tuoi script richiamano, gli strumenti che un assistente AI richiama, i codici di errore che registri e i kit per plugin con cui si costruisce un plugin. Questa pagina indica, per ciascuna di esse, cosa può cambiare un rilascio e cosa no. Una superficie che questa pagina non nomina non porta alcuna promessa oltre a quanto afferma la sua pagina di riferimento. L’ultima sezione indica dove un rilascio ti comunica che una di esse è cambiata. Le promesse di questa pagina valgono a partire dalla versione 0.9.0. Le Releases precedenti alla versione 0.9.0 non sono supportate: il registro dell’hub, hub.aggrega.ai, non fornisce alcuna versione di Plugin realizzata per esse, e i loro compilatori non sono in grado di leggerne il catalogo, i cui documenti dichiarano aggrega.ai/v1beta1.

Aggrega viene rilasciato in versioni 0.x.y: un rilascio di patch incrementa l’ultimo numero, un rilascio minore quello centrale. La metadata.version propria di un’entità del catalogo è una questione separata — la sceglie il suo autore, secondo i criteri di incremento di versione che aggrega lint --pre-publish verifica, e Risoluzione delle versioni descrive come un riferimento ne seleziona una.

Schemi

Ogni schema pubblicato da Aggrega appartiene a un’unica versione API, aggrega.ai/v1beta1 — il valore che un documento di entità dichiara nel suo apiVersion. La regola seguente si applica a ciascuno di essi: i tipi di entità, i payload dei plugin e gli schemi del workspace e gli altri — l’IR, la configurazione del workspace, i lockfile e il resto — tutti elencati nel Riferimento degli schemi. La versione API è separata dal numero di rilascio: molti rilasci leggono la stessa versione API.

Cosa può cambiare all’interno di v1beta1

All’interno di una versione API uno schema cambia solo in modo additivo, come Kubernetes fa con le proprie versioni API. Un rilascio può:

  • modificare una descrizione;
  • aggiungere un campo, quando il campo è opzionale.

Ogni documento valido prima di una tale modifica resta valido dopo di essa e ha lo stesso significato. Un programma che legge un documento scritto dal compilatore, come l’IR o un lockfile, deve accettare un campo che non conosce, perché un campo opzionale aggiunto può comparire in quell’output all’interno di v1beta1.

Cosa richiede v1beta2

Ciascuna di queste modifiche richiede una nuova versione API, aggrega.ai/v1beta2:

  • rimuovere o rinominare un campo;
  • rendere obbligatorio un campo;
  • restringere un tipo, o l’insieme di valori che un campo accetta;
  • cambiare il significato di un valore.

Una nuova versione API è una modifica incompatibile, pianificata e annunciata come tale nel rilascio che la introduce.

Un nuovo campo opzionale arriva in un catalogo insieme al compilatore che lo conosce

Il compilatore rifiuta un campo che il suo schema non dichiara. È questa rigidità a intercettare una chiave scritta male, e ha una conseguenza che un lettore non indovinerebbe: un’entità del catalogo può iniziare a usare un campo opzionale appena aggiunto solo in un rilascio che distribuisce un compilatore che conosce quel campo.

Ad esempio, supponiamo che un rilascio aggiunga un campo opzionale allo schema del Component — chiamiamolo spec.newField:

  1. Ogni Component scritto prima di quel rilascio resta valido; nessuno di essi imposta il campo.
  2. Un autore di catalogo pubblica una nuova versione di un Component che imposta spec.newField.
  3. Un compilatore di quel rilascio, o di uno successivo, convalida e compila il Component.
  4. Un compilatore di un rilascio precedente lo rifiuta, perché il suo schema non dichiara il campo: la convalida riporta spec.newField: unexpected property e indica la riga.

Quindi chi compila su quella versione del catalogo aggiorna prima al rilascio che ha aggiunto il campo, e un catalogo pubblica un’entità che usa il campo solo dopo che quel rilascio è uscito. Come una Release bloccata mantiene le versioni che ha risolto è descritto in Risoluzione delle versioni.

La riga di comando e gli strumenti dell’assistente

Script, pipeline di CI e configurazioni dell’assistente richiamano per nome i comandi aggrega, i flag e gli strumenti dell’assistente. Nei rilasci 0.x:

  • Un rilascio di patch non rimuove né rinomina mai un comando, un flag o uno strumento dell’assistente.
  • Un rilascio minore può rimuoverne o rinominarne uno, e il suo changelog lo indica sotto Removed o Changed.
  • Le aggiunte — un nuovo comando, flag o strumento — possono arrivare in qualsiasi rilascio.

Gli strumenti dell’assistente sono gli strumenti che aggrega mcp offre a un assistente connesso. Il loro elenco completo è la risposta del server stesso, e Cosa può fare il tuo assistente con Aggrega spiega come richiederlo. Uno strumento che esegue un comando prende il nome dal percorso di invocazione del comando, quindi rinominare un comando rinomina il suo strumento. La Panoramica della CLI elenca ogni comando.

Codici di errore

Ogni condizione di arresto porta un codice breve — la lettera E e quattro cifre, come in [DEVELOPER_ERROR E0007] — stampato all’inizio della sua diagnostica. I codici brevi sono un contratto pubblico: un codice viene assegnato una sola volta, non viene mai rinumerato e non viene mai dato a una condizione diversa. Il codice di una condizione ritirata resta ritirato, quindi un codice registrato in un runbook, in una regola di CI o in una issue indica la stessa condizione dopo ogni aggiornamento.

Sentinelle di errore spiega gli identificatori che una condizione porta — il codice breve che una persona cita, il codice descrittivo che un programma registra e l’accessor Go con cui un programma esegue il confronto — cosa promette ciascuno e come si impedisce che un numero ritirato venga assegnato di nuovo. La sua tabella di ogni condizione risolve ogni codice breve, compresi quelli ritirati, e aggrega explain ne risolve uno dal terminale.

Kit per Plugin

I kit di sviluppo per plugin — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust e @aggrega-ai/aggrega-pdk-typescript — e i codec aggrega-abi che essi riesportano seguono il versionamento semantico a partire da 0.9.0. I tre linguaggi dei kit condividono un unico numero di versione, e i tre linguaggi dei codec ne condividono un altro.

  • Un plugin costruito su una versione continua a essere costruito su ogni rilascio successivo della stessa linea. All’interno di 0.9.x un rilascio può aggiungere funzioni, tipi e costanti esportati, e non ne rimuove né modifica mai uno.
  • Una modifica incompatibile a un’API esportata viene distribuita solo in una nuova versione minore (da 0.9.x a 0.10.0), e un rilascio di patch non introduce mai incompatibilità. I kit e i codec passano a 1.0.0 insieme alla 1.0.0 di Aggrega stesso, dopodiché una modifica incompatibile incrementa il numero maggiore.
  • Una modifica incompatibile nei codec è una modifica incompatibile nei kit, che incrementano con essa la propria versione minore, perché riesportano i tipi dei codec.
  • Se un campo o un membro aggiunto a un tipo esistente conti come un’aggiunta dipende dal linguaggio. Il README di ciascun kit, pubblicato con il pacchetto, indica il caso del suo linguaggio nella sezione «Compatibility».

Questa promessa copre l’API che il sorgente di un plugin nomina. Ciò che passa tra il compilatore e un plugin in esecuzione è invece garantito dalla versione ABI dei plugin: all’interno di una versione ABI un socket acquisisce solo descrizioni e campi opzionali, quindi un plugin costruito su di essa continua a essere caricato. Il contratto dei plugin descrive i socket, e la guida per sviluppatori di plugin il flusso di lavoro che li circonda.

Cosa dice il changelog di un rilascio

Le note di ciascun rilascio, nella pagina dei rilasci, contengono il suo changelog, raggruppato sotto intestazioni come Added, Changed, Removed e Fixed. Per le superfici di questa pagina:

  • Un comando, un flag o uno strumento dell’assistente rimosso o rinominato è elencato sotto Removed o Changed, nel rilascio minore che apporta la modifica.
  • Una nuova versione API degli schemi viene annunciata come modifica incompatibile nel rilascio che la introduce.
  • Una modifica incompatibile ai kit per plugin o ai codec si vede nel loro numero di versione: è una nuova versione minore al di sotto di 1.0.0.
  • Un codice di errore non cambia mai significato, quindi nessun rilascio ne ha uno da annunciare.