AkurAI-Framework / site/content/docs/breaking-changes.md

Latest change 4ed55d17e0979479dc70291811217113b6062fa0 - docs: split AGENTS.md into domain-indexed subfiles + add breaking-changes guide by Ólafur Búi Ólafsson

# Breaking changes

AkurAI/Framework is **pre-1.0**. While the major version is `0`, a minor release
may include a breaking change — that's the cost of moving fast before the API
sets. We keep that cost honest: every breaking change is listed here with a
migration note, and flagged with a `### Breaking` entry in the
[changelog](/changelog) for the same version. Nothing breaks silently.

Once the framework reaches `1.0`, it follows strict semver: breaking changes only
ever land in a major version, and this page becomes the long-form migration
history behind each one.

Check this page before upgrading. Entries are reverse-chronological by version.

## 0.1.0 — current

**No breaking changes yet.** Every release so far has been purely additive — new
crates and features, nothing removed or changed out from under you. You can
upgrade across all `0.x` releases to date without changing any code, schema, or
config.

When that changes, the entry will follow the format below.

## Entry format (for future breaking changes)

Each breaking change gets a dated, versioned section like the worked example
below. Lead with what actually changed and why; then give concrete
before → after steps a reader can copy.

---

### Example — `0.5.0` (template; not a real change)

**What changed.** The `collections.toml` field key `type` was renamed to `kind`
to match the `/api/_meta` manifest, which already emitted `kind`.

**Why.** The declaration format and the self-describing manifest disagreed on a
single field name, so the same concept had two spellings depending on where you
looked. Aligning them removes a papercut and lets tooling read one vocabulary.

**Migrate.** Rename the key in every collection field in `backend/collections.toml`:

Before:

```toml
[[collections.posts.fields]]
name = "title"
type = "text"
required = true
```

After:

```toml
[[collections.posts.fields]]
name = "title"
kind = "text"
required = true
```

No data migration is needed — only the declaration file changes; stored records
are untouched. Restart `akurai serve` to pick up the new schema.

---

*This page is wired into the docs sidebar by the maintainers. To add an entry,
append a new `### <change> — <version>` section above the older ones and add the
matching `### Breaking` note to both changelogs.*