Przejdź do głównej zawartości
AggregaAggrega
Wybierz język: Polski
Ta strona została przetłumaczona maszynowo. Przeczytaj oryginał w języku angielskim.

Zgodność: co obiecuje wydanie

Aktualizacja Aggrega może zmienić kilka obszarów, na których się opiera: schematy, według których pisane są dokumenty, polecenia i flagi wywoływane przez skrypty, narzędzia wywoływane przez asystenta AI, rejestrowane kody błędów oraz zestawy deweloperskie, za pomocą których buduje się wtyczkę. Ta strona określa dla każdego z nich, co wydanie może zmienić, a czego nie zmienia. Obszar, którego ta strona nie wymienia, nie niesie żadnej obietnicy poza tym, co stwierdza jego własna strona referencyjna. Ostatnia sekcja wskazuje, gdzie wydanie informuje, że któryś z nich się zmienił. Obietnice z tej strony obowiązują od wersji 0.9.0. Releases sprzed wersji 0.9.0 nie są obsługiwane: rejestr hub, hub.aggrega.ai, nie udostępnia żadnej wersji Plugin przygotowanej dla nich, a ich kompilatory nie potrafią odczytać katalogu tego rejestru, którego dokumenty deklarują aggrega.ai/v1beta1.

Aggrega jest wydawana w wersjach 0.x.y: wydanie typu patch zwiększa ostatnią liczbę, a wydanie typu minor — środkową. Własna metadata.version encji katalogu to odrębna kwestia — wybiera ją jej autor, zgodnie z kryteriami podnoszenia wersji sprawdzanymi przez aggrega lint --pre-publish, a Rozwiązywanie wersji opisuje, jak odwołanie wybiera jedną z nich.

Schematy

Każdy schemat publikowany przez Aggrega należy do jednej wersji API, aggrega.ai/v1beta1 — wartości, którą dokument encji deklaruje w polu apiVersion. Poniższa zasada obejmuje każdy z nich: rodzaje encji, ładunki wtyczek oraz schematy obszaru roboczego i pozostałe — IR, konfigurację obszaru roboczego, pliki blokad i resztę — wszystkie wymienione w Dokumentacji referencyjnej schematów. Wersja API jest niezależna od numeru wydania: wiele wydań odczytuje tę samą wersję API.

Co może się zmienić w ramach v1beta1

W ramach jednej wersji API schemat zmienia się wyłącznie addytywnie, tak jak Kubernetes zmienia własne wersje API. Wydanie może:

  • zmienić opis;
  • dodać pole, jeśli pole jest opcjonalne.

Każdy dokument, który był poprawny przed taką zmianą, pozostaje poprawny po niej i znaczy to samo. Program odczytujący dokument zapisywany przez kompilator, taki jak IR lub plik blokady, musi akceptować pole, którego nie zna, ponieważ dodane opcjonalne pole może pojawić się w tym wyniku w ramach v1beta1.

Co wymaga v1beta2

Każda z tych zmian wymaga nowej wersji API, aggrega.ai/v1beta2:

  • usunięcie pola lub zmiana jego nazwy;
  • uczynienie pola wymaganym;
  • zawężenie typu lub zbioru wartości akceptowanych przez pole;
  • zmiana znaczenia wartości.

Nowa wersja API jest zmianą niezgodną wstecz, planowaną i ogłaszaną jako taka w wydaniu, które ją wprowadza.

Nowe opcjonalne pole trafia do katalogu wraz z kompilatorem, który je zna

Kompilator odrzuca pole, którego jego schemat nie deklaruje. To właśnie ta ścisłość wyłapuje błędnie zapisany klucz i ma jedną konsekwencję, której czytelnik by nie odgadł: encja katalogu może zacząć używać nowo dodanego opcjonalnego pola dopiero w wydaniu, które dostarcza kompilator znający to pole.

Załóżmy na przykład, że wydanie dodaje opcjonalne pole do schematu encji Component — nazwijmy je spec.newField:

  1. Każda encja Component napisana przed tym wydaniem pozostaje poprawna; żadna z nich nie ustawia tego pola.
  2. Autor katalogu publikuje nową wersję encji Component, która ustawia spec.newField.
  3. Kompilator z tego wydania lub z późniejszego waliduje i buduje encję Component.
  4. Kompilator z wcześniejszego wydania ją odrzuca, ponieważ jego własny schemat nie deklaruje tego pola: walidacja zgłasza spec.newField: unexpected property i wskazuje wiersz.

Zatem każdy, kto buduje względem tej wersji katalogu, najpierw aktualizuje do wydania, które dodało to pole, a katalog publikuje encję używającą tego pola dopiero po ukazaniu się tego wydania. To, jak zablokowana encja Release zachowuje rozwiązane wersje, opisano w sekcji Rozwiązywanie wersji.

Wiersz poleceń i narzędzia asystenta

Skrypty, potoki CI i konfiguracje asystentów wywołują po nazwie polecenia aggrega, flagi i narzędzia asystenta. W wydaniach 0.x:

  • Wydanie typu patch nigdy nie usuwa ani nie zmienia nazwy polecenia, flagi ani narzędzia asystenta.
  • Wydanie typu minor może usunąć jedno z nich lub zmienić jego nazwę, a jego dziennik zmian informuje o tym w sekcji Removed lub Changed.
  • Dodatki — nowe polecenie, flaga lub narzędzie — mogą pojawić się w dowolnym wydaniu.

Narzędzia asystenta to narzędzia, które aggrega mcp udostępnia podłączonemu asystentowi. Pełną ich listę stanowi odpowiedź samego serwera, a strona Co asystent może zrobić z Aggrega wyjaśnia, jak o nią poprosić. Narzędzie, które uruchamia polecenie, przyjmuje nazwę od ścieżki wywołania tego polecenia, więc zmiana nazwy polecenia zmienia nazwę jego narzędzia. Przegląd CLI wymienia wszystkie polecenia.

Kody błędów

Każdy warunek zatrzymujący niesie krótki kod — literę E i cztery cyfry, jak w [DEVELOPER_ERROR E0007] — wypisywany na początku jego komunikatu diagnostycznego. Krótkie kody są publicznym kontraktem: kod jest przydzielany raz, nigdy nie zmienia numeru i nigdy nie jest nadawany innemu warunkowi. Kod wycofanego warunku pozostaje wycofany, więc kod zapisany w runbooku, regule CI lub zgłoszeniu oznacza ten sam warunek po każdej aktualizacji.

Strona Sentinele błędów objaśnia identyfikatory, które niesie warunek — krótki kod, który cytuje człowiek, kod opisowy, który rejestruje program, i akcesor Go, z którym program porównuje — co każdy z nich obiecuje i jak zapobiega się ponownemu przydzieleniu wycofanego numeru. Jej tabela wszystkich warunków rozwiązuje każdy krótki kod, łącznie z wycofanymi, a aggrega explain rozwiązuje jeden z nich w terminalu.

Zestawy deweloperskie Plugin

Zestawy deweloperskie wtyczek — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust i @aggrega-ai/aggrega-pdk-typescript — oraz kodeki aggrega-abi, które one reeksportują, stosują wersjonowanie semantyczne od 0.9.0. Trzy języki zestawów dzielą jeden numer wersji, a trzy języki kodeków — inny.

  • Wtyczka zbudowana względem danej wersji nadal buduje się względem każdego późniejszego wydania tej samej linii. W ramach 0.9.x wydanie może dodawać eksportowane funkcje, typy i stałe, ale nigdy żadnych nie usuwa ani nie zmienia.
  • Zmiana niezgodna wstecz w eksportowanym API pojawia się wyłącznie w nowej wersji minor (z 0.9.x do 0.10.0), a wydanie typu patch nigdy nie łamie zgodności. Zestawy i kodeki przechodzą na 1.0.0 razem z własną wersją 1.0.0 Aggrega, po czym zmiana niezgodna wstecz podnosi numer główny.
  • Zmiana niezgodna wstecz w kodekach jest zmianą niezgodną wstecz w zestawach, które wraz z nią podnoszą własną wersję minor, ponieważ reeksportują typy kodeków.
  • To, czy pole lub składowa dodana do istniejącego typu liczy się jako dodatek, zależy od języka. README każdego zestawu, publikowane wraz z pakietem, opisuje przypadek jego języka w sekcji „Compatibility”.

Ta obietnica obejmuje API, do którego odwołuje się kod źródłowy wtyczki. To, co przechodzi między kompilatorem a działającą wtyczką, jest natomiast utrzymywane przez wersję ABI wtyczek: w ramach jednej wersji ABI gniazdo zyskuje wyłącznie opisy i pola opcjonalne, więc wtyczka zbudowana względem niej nadal się ładuje. Kontrakt wtyczek opisuje gniazda, a przewodnik dla twórców wtyczek — przepływ pracy wokół nich.

Co mówi dziennik zmian wydania

Informacje o każdym wydaniu na stronie wydań zawierają jego dziennik zmian, pogrupowany pod nagłówkami takimi jak Added, Changed, Removed i Fixed. W przypadku obszarów opisanych na tej stronie:

  • Usunięte lub przemianowane polecenie, flaga albo narzędzie asystenta jest wymienione w sekcji Removed lub Changed, w wydaniu typu minor, które wprowadza zmianę.
  • Nowa wersja API schematów jest ogłaszana jako zmiana niezgodna wstecz w wydaniu, które ją wprowadza.
  • Zmiana niezgodna wstecz w zestawach deweloperskich wtyczek lub kodekach jest widoczna w ich numerze wersji: jest to nowa wersja minor poniżej 1.0.0.
  • Kod błędu nigdy nie zmienia znaczenia, więc żadne wydanie nie ma w tej sprawie nic do ogłoszenia.