Формат журнала изменений

Как AACSearch фиксирует изменения по API, SDK, виджету, коннекторам и дашборду. Шесть бакетов в стиле Keep-a-Changelog с явными migration-нотами для breaking-изменений.

AACSearch использует формат в стиле Keep a Changelog с шестью бакетами и небольшим набором соглашений под мульти-продуктовую поверхность (API, SDK, виджет, коннекторы, дашборд).

Шесть бакетов

Каждая запись под датой/релизом попадает ровно в один из:

Бакет	Когда использовать
Added	Новая функция, эндпоинт, параметр, страница, опция конфигурации.
Changed	Поведение существующей функции изменилось обратно совместимо (defaults, копия, рендер, производительность).
Fixed	Bugfix, устраняющий некорректное поведение. Описываем симптом, не имплементацию.
Deprecated	Функция всё ещё работает, но будет удалена. Обязательно указываем target удаления (дата или релиз).
Removed	Функция удалена. Обязательно дата удаления и ссылка на migration guide, если есть.
Security	Security-релевантное изменение. CVE / advisory ID — если публичный; severity — иначе.

Порядок внутри даты/релиза: Added → Changed → Fixed → Deprecated → Removed → Security. Пустые бакеты пропускаем.

Сводный /changelog — хронологический фид всего user-facing. У каждого компонента есть отдельная страница, чтобы потребитель именно этой поверхности (например, апгрейдер SDK) мог следить за нужным срезом без нерелевантного шума:

API — изменения REST + oRPC + webhook payload.
SDK — release notes @aacsearch/client, @aacsearch/react, @aacsearch/widget, Python SDK.
Widget — @aacsearch/widget (vanilla JS, Shadow DOM).
Connectors — webhook-коннекторы платформ (PrestaShop, Bitrix, Shopify, в будущем — другие).

Одно изменение часто попадает в две точки (API-добавление, к которому вышел SDK-метод). Не дублируем текст — каноническая запись в одной странице, кросс-ссылка из другой.

Анатомия записи

### Added

- **Search**: Открыли параметр `include_fields` для JOIN в search-процедурах.
  `SearchDocumentsInput.includeFields` принимает синтаксис JOIN
  `$Category(id, name)`. (AAC-569)

Обязательно:

Жирный scope-tag — область кода (Search, Widget, Knowledge, Billing, Dashboard, API, SDK, Connectors, Auth, Marketing).
Первое предложение описывает user-visible поведение, не имплементацию. "Синонимы теперь применяются в multi-search" — лучше чем "отрефакторили synonym matcher".
Issue/task ref в скобках (AAC-XXX, #NN) — чтобы трассировать.

Опционально:

Маркер breaking change: префиксуем bullet ⚠ Breaking для любого изменения, требующего действия читателя. Всегда сопровождается migration-нотой.
Code/curl-сниппет для добавленных/изменённых API.

Breaking changes и migration-ноты

Изменение breaking, если требует от существующего клиента обновить код, конфиг или данные. Для каждого breaking:

Маркер ⚠ Breaking в бакете (обычно Changed или Removed).
Открываем соответствующую запись в /migration/<from-version>, если миграция длиннее двух предложений.
Линкуем на migration-страницу из changelog-записи.
Упоминаем в release-анонсе/блоге, если он есть.

Тихих breaking changes избегаем — доверие они подрывают быстрее, чем любая фича его строит.

Связь с roadmap

Roadmap-айтемы из Status & Roadmap ссылаются на этот changelog при отгрузке. Конвенция:

Roadmap-айтем → "Shipped 2026-05-11. См. Changelog 2026-05-11."
Для multi-month вехи: "Shipped в v0.6. См. API changelog → v0.6."

Per-page status-бейджи

Страницы фич, которые недавно зашипились, носят status: new во frontmatter ~30 дней. Это пуллит страницу в "Recently shipped" на docs-главной, потом снимается на следующем sweep.

Вне scope формата

Эта страница описывает changelog. Коммуникация SLA / uptime / доступности и инцидентов принадлежит /operations/status (Roadmap v1.0 — см. Claim status) и не входит в changelog.