Changelog format

[TODO i18n — see issue #76] How AACSearch records changes across the API, SDKs, widget, connectors and dashboard. Six-bucket Keep-a-Changelog format with explicit migration notes for breaking changes.

AACSearch follows a Keep a Changelog-style format with six buckets and a small set of conventions tailored to a multi-product surface (API, SDKs, widget, connectors, dashboard).

The six buckets

Every entry under a date or release header belongs in exactly one of:

Bucket	When to use
Added	A new feature, endpoint, parameter, page, configuration option or capability.
Changed	An existing feature's behavior changed in a backwards-compatible way (defaults, copy, rendering, performance).
Fixed	A bug fix that resolved incorrect behavior. Reference the symptom, not the implementation detail.
Deprecated	Feature still works but will be removed. Must include the removal target (date or release).
Removed	Feature is gone. Must include the removal date and a link to the migration guide if any.
Security	Security-relevant change. CVE / advisory ID if public; severity if not.

Order within a date or release: Added → Changed → Fixed → Deprecated → Removed → Security. Skip empty buckets.

Per-component changelogs

The aggregate /changelog is a chronological feed of everything user-facing. Each component also has its own page so that consumers of that surface alone (e.g. SDK upgraders) can subscribe to the relevant slice without scrolling past unrelated work:

API — REST + oRPC + webhook payload changes.
SDK — @aacsearch/client, @aacsearch/react, @aacsearch/widget, Python SDK release notes.
Widget — @aacsearch/widget (vanilla JS, Shadow DOM).
Connectors — webhook connector platforms (PrestaShop, Bitrix, Shopify, future).

A single change frequently lands in two places (e.g. an API addition that ships an SDK method). Cross-link rather than duplicate text — use the canonical entry as the source of truth and reference it from the other page.

Anatomy of a single entry

### Added

- **Search**: Exposed `include_fields` JOIN parameter in search procedures.
  `SearchDocumentsInput.includeFields` now accepts AACSearch JOIN syntax
  like `$Category(id, name)`. (AAC-569)

Required:

Bold scope tag — area of the codebase (Search, Widget, Knowledge, Billing, Dashboard, API, SDK, Connectors, Auth, Marketing).
First sentence describes user-visible behavior — not the implementation. "Synonyms now apply to multi-search" beats "refactored the synonym matcher".
Issue or task ref in parentheses (AAC-XXX, #NN) so readers can trace back.

Optional:

Breaking change indicator: prefix the bullet with ⚠ Breaking for any change that requires reader action. Always paired with a migration note.
Code or curl snippet for added/changed APIs.

Breaking changes and migration notes

A change is breaking when it requires an existing customer to update code, config or data. For every breaking change:

Mark the entry ⚠ Breaking in the bucket where it lands (usually Changed or Removed).
Open a corresponding entry in /migration/<from-version> if the migration spans more than two sentences.
Link to the migration page from the changelog entry.
Mention the change in the release announcement / blog post if there is one.

Avoid silent breaking changes — they erode trust faster than any feature ships it.

Linking to roadmap

Roadmap items in Status & Roadmap reference this changelog when they ship. The convention is one of:

Roadmap item → "Shipped 2026-05-11. See Changelog 2026-05-11."
Or, for a multi-month milestone: "Shipped in v0.6. See API changelog → v0.6."

Per-page status badges

Pages describing a feature that recently landed should carry a status: new frontmatter flag for ~30 days. This pulls the page into the "Recently shipped" section of the docs home, and is dropped on next sweep.

Out of scope for this format

This page documents the changelog. SLA / uptime / availability incident communication is owned by /operations/status (Roadmap v1.0 — see Claim status) and is not part of the changelog.