Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Kompatibilität: Was eine Veröffentlichung verspricht

Ein Upgrade von Aggrega kann mehrere Schnittstellen ändern, auf denen Sie aufbauen: die Schemas, gegen die Ihre Dokumente geschrieben sind, die Befehle und Flags, die Ihre Skripte aufrufen, die Tools, die ein KI-Assistent aufruft, die Fehlercodes, die Sie festhalten, und die Plugin-Kits, mit denen ein Plugin gebaut wird. Diese Seite legt für jede davon fest, was eine Veröffentlichung ändern darf und was nicht. Eine Schnittstelle, die diese Seite nicht nennt, trägt kein Versprechen über das hinaus, was ihre eigene Referenzseite angibt. Der letzte Abschnitt sagt, wo eine Veröffentlichung Ihnen mitteilt, dass sich eine davon geändert hat. Die Versprechen auf dieser Seite gelten ab 0.9.0. Releases vor 0.9.0 werden nicht unterstützt: Die Hub-Registry, hub.aggrega.ai, stellt keine Plugin-Version bereit, die für sie erstellt wurde, und deren Compiler können den Katalog dieser Registry nicht lesen, dessen Dokumente aggrega.ai/v1beta1 deklarieren.

Aggrega wird in Versionen 0.x.y veröffentlicht: Eine Patch-Version erhöht die letzte Zahl, eine Minor-Version die mittlere. Die eigene metadata.version einer Katalog-Entität ist eine separate Angelegenheit — ihr Autor wählt sie, nach den Kriterien zur Versionserhöhung, die aggrega lint --pre-publish prüft, und Versionsauflösung beschreibt, wie eine Referenz eine davon auswählt.

Schemas

Jedes Schema, das Aggrega veröffentlicht, gehört zu einer API-Version, aggrega.ai/v1beta1 — dem Wert, den ein Entitätsdokument in seinem apiVersion deklariert. Die folgende Regel gilt für jedes davon: die Entitätsarten, die Plugin-Payloads sowie die Workspace- und sonstigen Schemas — die IR, die Workspace-Konfiguration, die Lockfiles und der Rest —, alle aufgeführt in der Schema-Referenz. Die API-Version ist von der Nummer der Veröffentlichung getrennt: Viele Veröffentlichungen lesen dieselbe API-Version.

Was sich innerhalb von v1beta1 ändern darf

Innerhalb einer API-Version ändert sich ein Schema nur additiv, so wie Kubernetes seine eigenen API-Versionen ändert. Eine Veröffentlichung darf:

  • eine Beschreibung ändern;
  • ein Feld hinzufügen, wenn das Feld optional ist.

Jedes Dokument, das vor einer solchen Änderung gültig war, ist danach weiterhin gültig und bedeutet dasselbe. Ein Programm, das ein vom Compiler geschriebenes Dokument liest, etwa die IR oder ein Lockfile, muss ein Feld akzeptieren, das es nicht kennt, da ein hinzugefügtes optionales Feld innerhalb von v1beta1 in dieser Ausgabe erscheinen kann.

Was v1beta2 erfordert

Jede dieser Änderungen erfordert eine neue API-Version, aggrega.ai/v1beta2:

  • ein Feld entfernen oder umbenennen;
  • ein Feld zur Pflicht machen;
  • einen Typ einschränken oder die Menge der Werte, die ein Feld akzeptiert;
  • ändern, was ein Wert bedeutet.

Eine neue API-Version ist eine inkompatible Änderung, die als solche in der Veröffentlichung, die sie bringt, geplant und angekündigt wird.

Ein neues optionales Feld erreicht einen Katalog mit dem Compiler, der es kennt

Der Compiler lehnt ein Feld ab, das sein Schema nicht deklariert. Diese Strenge fängt einen falsch geschriebenen Schlüssel ab, und sie hat eine Folge, die ein Leser nicht erraten würde: Eine Katalog-Entität darf ein neu hinzugefügtes optionales Feld erst in einer Veröffentlichung verwenden, die einen Compiler ausliefert, der dieses Feld kennt.

Angenommen, eine Veröffentlichung fügt dem Component-Schema ein optionales Feld hinzu — nennen wir es spec.newField:

  1. Jede Component, die vor dieser Veröffentlichung geschrieben wurde, ist weiterhin gültig; keine davon setzt das Feld.
  2. Ein Katalogautor veröffentlicht eine neue Version einer Component, die spec.newField setzt.
  3. Ein Compiler aus dieser oder einer späteren Veröffentlichung validiert und baut die Component.
  4. Ein Compiler aus einer früheren Veröffentlichung lehnt sie ab, weil sein eigenes Schema das Feld nicht deklariert: Die Validierung meldet spec.newField: unexpected property und nennt die Zeile.

Wer also gegen diese Katalogversion baut, aktualisiert zuerst auf die Veröffentlichung, die das Feld hinzugefügt hat, und ein Katalog veröffentlicht eine Entität, die das Feld verwendet, erst, wenn diese Veröffentlichung erschienen ist. Wie ein festgeschriebenes Release die aufgelösten Versionen beibehält, steht in Versionsauflösung.

Die Befehlszeile und die Assistenten-Tools

Skripte, CI-Pipelines und Assistenten-Konfigurationen rufen aggrega-Befehle, Flags und Assistenten-Tools beim Namen auf. In den 0.x-Veröffentlichungen:

  • Eine Patch-Version entfernt niemals einen Befehl, ein Flag oder ein Assistenten-Tool und benennt keines davon um.
  • Eine Minor-Version darf eines davon entfernen oder umbenennen, und ihr Changelog vermerkt dies unter Removed oder Changed.
  • Ergänzungen — ein neuer Befehl, ein neues Flag oder Tool — können in jeder Veröffentlichung kommen.

Die Assistenten-Tools sind die Tools, die aggrega mcp einem verbundenen Assistenten anbietet. Die Antwort des Servers selbst ist ihre vollständige Liste, und Was Ihr Assistent mit Aggrega tun kann beschreibt, wie Sie sie abfragen. Ein Tool, das einen Befehl ausführt, erhält seinen Namen vom Aufrufpfad des Befehls, sodass das Umbenennen eines Befehls auch sein Tool umbenennt. Die CLI-Übersicht listet jeden Befehl auf.

Fehlercodes

Jede abbrechende Bedingung trägt einen Kurzcode — den Buchstaben E und vier Ziffern, wie in [DEVELOPER_ERROR E0007] —, der am Anfang ihrer Diagnose ausgegeben wird. Die Kurzcodes sind ein öffentlicher Vertrag: Ein Code wird einmal vergeben, nie neu nummeriert und nie einer anderen Bedingung zugewiesen. Der Code einer zurückgezogenen Bedingung bleibt zurückgezogen, sodass ein Code, der in einem Runbook, einer CI-Regel oder einem Issue festgehalten ist, nach jedem Upgrade dieselbe Bedingung bezeichnet.

Fehler-Sentinels erklärt die Bezeichner, die eine Bedingung trägt — den Kurzcode, den eine Person zitiert, den beschreibenden Code, den ein Programm festhält, und den Go-Accessor, gegen den ein Programm abgleicht —, was jeder davon verspricht und wie verhindert wird, dass eine zurückgezogene Nummer erneut vergeben wird. Ihre Tabelle aller Bedingungen löst jeden Kurzcode auf, zurückgezogene eingeschlossen, und aggrega explain löst einen davon im Terminal auf.

Plugin-Kits

Die Plugin-Entwicklungskits — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust und @aggrega-ai/aggrega-pdk-typescript — sowie die aggrega-abi-Codecs, die sie re-exportieren, folgen ab 0.9.0 der semantischen Versionierung. Die drei Sprachen der Kits teilen sich eine Versionsnummer, und die drei Sprachen der Codecs teilen sich eine andere.

  • Ein Plugin, das gegen eine Version gebaut wurde, lässt sich weiterhin gegen jede spätere Veröffentlichung derselben Linie bauen. Innerhalb von 0.9.x darf eine Veröffentlichung exportierte Funktionen, Typen und Konstanten hinzufügen und entfernt oder ändert niemals eine davon.
  • Eine inkompatible Änderung an einer exportierten API erscheint nur in einer neuen Minor-Version (0.9.x zu 0.10.0), und eine Patch-Version bricht niemals die Kompatibilität. Die Kits und Codecs wechseln auf 1.0.0 zusammen mit der eigenen 1.0.0 von Aggrega, danach erhöht eine inkompatible Änderung die Major-Nummer.
  • Eine inkompatible Änderung in den Codecs ist eine inkompatible Änderung in den Kits, die damit ihre eigene Minor-Version erhöhen, weil sie die Codec-Typen re-exportieren.
  • Ob ein Feld oder Member, das einem bestehenden Typ hinzugefügt wird, als Ergänzung zählt, hängt von der Sprache ab. Die README jedes Kits, die mit dem Paket veröffentlicht wird, beschreibt den Fall ihrer Sprache unter „Compatibility“.

Dieses Versprechen deckt die API ab, die der Quellcode eines Plugins benennt. Was zwischen dem Compiler und einem laufenden Plugin übertragen wird, regelt stattdessen die ABI-Version der Plugins: Innerhalb einer ABI-Version erhält ein Socket nur Beschreibungen und optionale Felder, sodass ein dagegen gebautes Plugin weiterhin geladen wird. Der Plugin-Vertrag beschreibt die Sockets und der Leitfaden für Plugin-Entwickler den Arbeitsablauf darum herum.

Was das Changelog einer Veröffentlichung sagt

Die Notizen jeder Veröffentlichung auf der Seite der Veröffentlichungen enthalten ihr Changelog, gruppiert unter Überschriften wie Added, Changed, Removed und Fixed. Für die Schnittstellen auf dieser Seite:

  • Ein Befehl, Flag oder Assistenten-Tool, das entfernt oder umbenannt wurde, wird unter Removed oder Changed aufgeführt, in der Minor-Version, die die Änderung vornimmt.
  • Eine neue Schema-API-Version wird in der Veröffentlichung, die sie bringt, als inkompatible Änderung angekündigt.
  • Eine inkompatible Änderung an den Plugin-Kits oder Codecs zeigt sich in ihrer Versionsnummer: Sie ist eine neue Minor-Version unterhalb von 1.0.0.
  • Ein Fehlercode ändert nie seine Bedeutung, daher hat keine Veröffentlichung einen anzukündigen.