Политика версионирования и прекращения поддержки

Эта страница описывает, как AACSearch версионирует каждую публичную поверхность и срок жизни устаревшей функции.

Версионирование API

REST API версионируется в URL: /api/v1/.... Новые версии появляются, когда:

• Форма ответа изменяется обратно несовместимым образом.
• Обязательное поле добавляется или удаляется.
• Требование аутентификации изменяется (например, расширяется применение scope-токенов).

Аддитивные изменения (новые необязательные поля, новые эндпоинты, новые необязательные параметры) не вызывают появления новой мажорной версии. Они попадают в текущую версию с записью Changed/Added в журнале изменений.

Текущие мажорные версии в продакшене:

Мы избегаем создания новой мажорной версии, если только аддитивное решение действительно невозможно. Новые мажорные версии имеют 12-месячный период пересечения с предыдущей мажорной версией.

Версионирование SDK

Каждый пакет SDK следует Semver:

• MAJOR — критическое изменение API самого SDK или нижележащей поверхности REST, на которую он нацелен.
• MINOR — новые методы, новые необязательные аргументы, новые типы.
• PATCH — исправления ошибок, внутренняя очистка, обновление зависимостей без изменения поверхности API.

Отслеживаемые пакеты SDK:

• @aacsearch/client — TypeScript SDK для браузера и сервера.
• @aacsearch/react — React-хуки (useAACsearch, useAACSuggest, useAACFacet).
• @aacsearch/widget — Vanilla JS виджет на Shadow DOM.
• aacsearch (Python) — Python-клиент.

Заметки о выпусках публикуются в /changelog/sdk. Каждый выпуск имеет git tag, соответствующий версии npm/pip, и запись о выпуске на этой странице документации.

Версионирование виджета

Виджет — это UMD/ES-бандл, загружаемый через тег <script>. Версии закреплены в URL:

<script src="https://cdn.aacsearch.com/widget/v1/widget.js"></script>

Канал latest указывает на последнюю стабильную мажорную версию. Закрепление за мажорной версией (v1, v2) разрешено и рекомендуется для продакшена. Закрепление за точным патчем разрешено, но не рекомендуется — патчи содержат исправления безопасности.

Критические изменения всегда ждут нового мажорного URL. Предыдущая мажорная версия остаётся доступной на CDN в течение 12 месяцев после выпуска новой мажорной версии.

Версионирование протокола коннектора

Версии протокола коннектора — это отдельный поток. platform.minModuleVersion, возвращаемый из /api/connectors/handshake, объявляет минимальную версию, которой должен соответствовать модуль коннектора на стороне клиента. Когда этот порог повышается, изменение публикуется в /changelog/connectors с уведомлением за 60 дней для существующих модулей коннекторов.

Сроки прекращения поддержки

Каждое прекращение поддержки должно:

1. Попасть в раздел Deprecated соответствующей страницы журнала изменений.
2. Содержать дату удаления в записи.
3. Иметь страницу миграции в /migration/<from-version>, если миграция занимает больше нескольких строк.
4. Вызывать заголовок ответа X-Deprecated на поверхности API в течение периода уведомления.

Версионирование документации

Документация не версионируется по выпускам — живой сайт /docs отражает текущее состояние продакшена. При смене мажорной версии API:

• Документация предыдущей мажорной версии перемещается в /docs/v<n>/....
• Документация новой мажорной версии заменяет /docs/....
• Страница /migration/v<n>-to-v<n+1> описывает, что изменилось.

Историческая документация для vN остаётся доступной только для чтения до закрытия окна прекращения поддержки vN.

Связывание с журналом изменений

Каждая запись журнала изменений, вводящая версионированное изменение поверхности, должна ссылаться сюда. Формат:

### Изменено

- **API**: Ответ поиска теперь включает поле `tookMs`. Аддитивное —
  повышение версии не требуется. См. [Версионирование](/changelog/versioning)
  для правила версионирования.

Вне области

• Предрелизные теги (alpha, beta, rc) следуют правилам предрелизов npm semver; документирование их точного значения для каждого пакета — задача заметок о выпусках SDK.
• Обновления внутренних инфраструктурных версий (Postgres, Typesense и т.д.) не являются пользовательскими и не перечисляются в этом журнале изменений.