Совместимость: что обещает релиз
Обновление 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:
- Каждая сущность Component, написанная до этого релиза, остаётся валидной; ни одна из них не задаёт это поле.
- Автор каталога публикует новую версию сущности Component, которая задаёт
spec.newField. - Компилятор из этого или более позднего релиза проверяет и собирает сущность Component.
- Компилятор из более раннего релиза отклоняет её, потому что его собственная схема не объявляет это поле: проверка сообщает
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.0Aggrega, после чего несовместимое изменение повышает мажорный номер. - Несовместимое изменение в кодеках — это несовместимое изменение в наборах, которые вместе с ним повышают собственную минорную версию, поскольку реэкспортируют типы кодеков.
- Считается ли поле или член, добавленный к существующему типу, дополнением, зависит от языка. README каждого набора, публикуемый вместе с пакетом, описывает случай своего языка в разделе «Compatibility».
Это обещание распространяется на API, который называет исходный код плагина. То, что передаётся между компилятором и работающим плагином, обеспечивается вместо этого версией ABI плагинов: в пределах одной версии ABI сокет получает только описания и необязательные поля, поэтому плагин, собранный с ней, продолжает загружаться. Контракт плагинов описывает сокеты, а руководство разработчика плагинов — рабочий процесс вокруг них.
Что сообщает журнал изменений релиза
Примечания к каждому релизу на странице релизов содержат его журнал изменений, сгруппированный под заголовками вроде Added, Changed, Removed и Fixed. Для поверхностей, описанных на этой странице:
- Удалённая или переименованная команда, флаг или инструмент ассистента указывается в разделе Removed или Changed в минорном релизе, который вносит изменение.
- Новая версия API схем объявляется как несовместимое изменение в релизе, который её приносит.
- Несовместимое изменение наборов для разработки плагинов или кодеков видно по их номеру версии: это новая минорная версия ниже
1.0.0. - Код ошибки никогда не меняет смысла, поэтому ни одному релизу не нужно о нём объявлять.