Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Сумісність: що обіцяє випуск

Оновлення Aggrega може змінити кілька поверхонь, на які ви спираєтеся: схеми, згідно з якими написані ваші документи, команди й прапорці, які викликають ваші скрипти, інструменти, які викликає ШІ-асистент, коди помилок, які ви записуєте, і набори для розробки плагінів, за допомогою яких збирається плагін. Ця сторінка визначає для кожної з них, що випуск може змінити, а чого не змінює. Поверхня, яку ця сторінка не називає, не несе жодних обіцянок понад те, що зазначено на її власній довідковій сторінці. Останній розділ вказує, де випуск повідомляє вам, що одна з них змінилася. Обіцянки на цій сторінці діють починаючи з версії 0.9.0. Releases до версії 0.9.0 не підтримуються: реєстр hub, hub.aggrega.ai, не надає жодної версії Plugin, створеної для них, а їхні компілятори не можуть прочитати каталог цього реєстру, документи якого оголошують aggrega.ai/v1beta1.

Aggrega випускається у версіях 0.x.y: патч-випуск збільшує останнє число, мінорний випуск — середнє. Власна metadata.version сутності каталогу — окрема справа: її обирає автор відповідно до критеріїв підвищення версії, які перевіряє aggrega lint --pre-publish, а Розв’язання версій описує, як посилання обирає одну з них.

Схеми

Кожна схема, яку публікує Aggrega, належить до однієї версії API, aggrega.ai/v1beta1, — значення, яке документ сутності оголошує у своєму apiVersion. Наведене нижче правило охоплює кожну з них: типи сутностей, корисні навантаження плагінів, а також схеми робочого простору та інші — IR, конфігурацію робочого простору, файли блокування тощо, — усі вони перелічені в Довіднику схем. Версія API не залежить від номера випуску: багато випусків читають ту саму версію API.

Що може змінюватися в межах v1beta1

У межах однієї версії API схема змінюється лише адитивно, так само як Kubernetes змінює власні версії API. Випуск може:

  • змінити опис;
  • додати поле, якщо поле необов’язкове.

Кожен документ, який був дійсним до такої зміни, залишається дійсним і після неї та означає те саме. Програма, що читає документ, який записує компілятор, наприклад IR або файл блокування, має приймати поле, якого вона не знає, оскільки додане необов’язкове поле може з’явитися в цьому виводі в межах v1beta1.

Що потребує v1beta2

Кожна з цих змін потребує нової версії API, aggrega.ai/v1beta2:

  • вилучення або перейменування поля;
  • перетворення поля на обов’язкове;
  • звуження типу або множини значень, які приймає поле;
  • зміна того, що означає значення.

Нова версія API — це несумісна зміна, яку планують і оголошують як таку у випуску, що її приносить.

Нове необов’язкове поле потрапляє до каталогу разом із компілятором, який його знає

Компілятор відхиляє поле, якого не оголошує його схема. Саме ця суворість виявляє помилково написаний ключ, і вона має один наслідок, про який читач не здогадався б: сутність каталогу може почати використовувати щойно додане необов’язкове поле лише у випуску, який постачає компілятор, що знає це поле.

Наприклад, припустімо, що випуск додає необов’язкове поле до схеми сутності Component — назвімо його spec.newField:

  1. Кожна сутність Component, написана до цього випуску, залишається дійсною; жодна з них не задає це поле.
  2. Автор каталогу публікує нову версію сутності Component, яка задає spec.newField.
  3. Компілятор із цього випуску або пізнішого перевіряє та збирає сутність Component.
  4. Компілятор із ранішого випуску відхиляє її, оскільки його власна схема не оголошує це поле: перевірка повідомляє spec.newField: unexpected property і вказує рядок.

Тож той, хто збирає на основі цієї версії каталогу, спершу оновлюється до випуску, який додав це поле, а каталог публікує сутність, що використовує це поле, лише після виходу цього випуску. Як заблокована сутність Release зберігає розв’язані нею версії, описано в розділі Розв’язання версій.

Командний рядок та інструменти асистента

Скрипти, конвеєри CI та конфігурації асистентів викликають команди aggrega, прапорці та інструменти асистента за назвою. У випусках 0.x:

  • Патч-випуск ніколи не вилучає й не перейменовує команду, прапорець або інструмент асистента.
  • Мінорний випуск може вилучити або перейменувати один із них, і його журнал змін повідомляє про це в розділі Removed або Changed.
  • Доповнення — нова команда, прапорець або інструмент — можуть з’явитися в будь-якому випуску.

Інструменти асистента — це інструменти, які aggrega mcp пропонує підключеному асистенту. Повний їх перелік — це відповідь самого сервера, а сторінка Що ваш асистент може робити з Aggrega пояснює, як його запросити. Інструмент, що запускає команду, бере назву від шляху виклику команди, тож перейменування команди перейменовує і її інструмент. Огляд CLI перелічує всі команди.

Коди помилок

Кожна умова зупинки має короткий код — літеру E і чотири цифри, як у [DEVELOPER_ERROR E0007], — що виводиться на початку її діагностичного повідомлення. Короткі коди — це публічний контракт: код видається один раз, ніколи не перенумеровується й ніколи не надається іншій умові. Код виведеної з ужитку умови залишається виведеним з ужитку, тож код, записаний у runbook, правилі CI або issue, позначає ту саму умову після кожного оновлення.

Сторінка Сентинели помилок пояснює ідентифікатори, які має умова, — короткий код, який цитує людина, описовий код, який записує програма, і аксесор Go, з яким програма зіставляє, — що обіцяє кожен із них і як запобігти повторній видачі виведеного з ужитку номера. Її таблиця всіх умов розв’язує кожен короткий код, зокрема виведені з ужитку, а aggrega explain розв’язує один код у терміналі.

Набори для розробки Plugin

Набори для розробки плагінів — github.com/aggrega-ai/aggrega-pdk/go, aggrega-pdk-rust і @aggrega-ai/aggrega-pdk-typescript — та кодеки aggrega-abi, які вони реекспортують, дотримуються семантичного версіонування починаючи з 0.9.0. Три мови наборів мають спільний номер версії, а три мови кодеків — інший.

  • Плагін, зібраний із певною версією, і далі збирається з кожним пізнішим випуском тієї самої лінійки. У межах 0.9.x випуск може додавати експортовані функції, типи й константи і ніколи не вилучає та не змінює жодної з них.
  • Несумісна зміна експортованого API виходить лише в новій мінорній версії (з 0.9.x до 0.10.0), а патч-випуск ніколи не порушує сумісності. Набори й кодеки переходять на 1.0.0 разом із власною версією 1.0.0 Aggrega, після чого несумісна зміна підвищує мажорний номер.
  • Несумісна зміна в кодеках є несумісною зміною в наборах, які разом із нею підвищують власну мінорну версію, оскільки реекспортують типи кодеків.
  • Чи вважається поле або член, доданий до наявного типу, доповненням, залежить від мови. README кожного набору, опублікований разом із пакетом, описує випадок своєї мови в розділі «Compatibility».

Ця обіцянка охоплює API, який називає вихідний код плагіна. Те, що передається між компілятором і запущеним плагіном, натомість забезпечує версія ABI плагінів: у межах однієї версії ABI сокет отримує лише описи й необов’язкові поля, тож плагін, зібраний із нею, і далі завантажується. Контракт плагінів описує сокети, а посібник розробника плагінів — робочий процес навколо них.

Що повідомляє журнал змін випуску

Примітки до кожного випуску на сторінці випусків містять його журнал змін, згрупований під заголовками на кшталт Added, Changed, Removed і Fixed. Для поверхонь, описаних на цій сторінці:

  • Вилучену або перейменовану команду, прапорець чи інструмент асистента наводять у розділі Removed або Changed у мінорному випуску, який вносить зміну.
  • Нову версію API схем оголошують як несумісну зміну у випуску, що її приносить.
  • Несумісну зміну наборів для розробки плагінів або кодеків видно з їхнього номера версії: це нова мінорна версія нижче 1.0.0.
  • Код помилки ніколи не змінює значення, тож жодному випуску не доводиться оголошувати такої зміни.