The overlay contract

What a projects/<name>/ subproject may rely on, what it may not, and what happens when something it relies on has to change.

Two other documents already own neighbouring ground, and this one does not repeat them: Downstream projects describes the mechanics — how an overlay attaches, how it is activated and built — and CHANGELOG.md defines what major, minor and patch mean here. The question neither answers is the one a team has to answer before pinning a CMS core to their product: which surfaces does the major-bump promise actually cover? That is this document.

The promise in one sentence: a minor release must leave your projects/ tree compiling, booting, and reading its own data unchanged. If it cannot, the release is a major, and mix kiln.update will refuse to move your pin without --allow-major.

Every surface, labelled

Every surface of the core carries exactly one of three labels. The sections after this one argue the overlay contract in detail; this table is the summary, and the README carries the same table word for word.

Covered surfaces

A rename, a removal, or a change of meaning in anything below is a breaking change and forces a major bump. Additions to these surfaces are not breaking — for a module that implements a behaviour through its use form. A module that hand-rolls @behaviour instead is covered for the callbacks that exist, but a minor may add one, and that is not a major (see What a minor may still do to you).

Since #1909, Kiln.Plugin, Kiln.Block and its Kiln.Block.* modules, Kiln.FieldType, Kiln.Tokens, Kiln.Forms.SpamCheck (with its Context), Kiln.ImageBackend and, since kiln_plugin 1.3, Kiln.SafeFetch ship in the kiln_plugin package, which the core takes as a path: dependency, so that a plugin can depend on them without depending on the core. The names did not change and the promises above apply unchanged; an overlay compiles exactly as before. The package versions on its own (kiln_plugin-vX.Y.Z) under the same rule: minors add, and a major comes only with a core major. Kiln.Plugins, Kiln.Advisory, Kiln.Version, Kiln.Updates and the three registries stay in the core.

Delivery URLs, GraphQL field names and JSON:API routes are derived from :type and :plural, so they inherit the promise above — but the HTTP contract has its own, stricter policy, including a versioned-prefix migration path. See Versioning & stability in the API guide; where the two documents disagree about an HTTP surface, that one wins.

Not covered

These may change in any release, including a patch. If your overlay reaches for one, it is reaching past the contract, and an upgrade may break it without that counting as a major.

• Everything under KilnCMSWeb.* except KilnCMSWeb.PluginRouter and KilnCMSWeb.AshJsonApiRouter — LiveViews, components, the component kit's class names, and the /editor/... admin paths themselves.

• KilnCMS.* internals not named above — changes, calculations, workers, firing internals, and anything marked @doc false.

• The console's own side-* classes and admin design tokens. Those are the admin skin, and they are re-cut whenever the console is redesigned. Only the public-* classes on delivery pages are contract.

• Core Oban queue names, and the internal write actions a content resource carries for its own bookkeeping — the ones outside the workflow set named above, which exist to record an embedding, a search reindex, or a published version id. One caveat on the queues: the name space is shared even though individual names are not promised, so a core minor that adds a queue your plugin already declares turns mix kiln.plugins.doctor red.

• Search ranking behaviour and its tuning defaults. New legs and re-tuned weights ship in minors; a query's result order is not a stable interface, even though the functions that run it are.

• The generated GraphQL schema module itself, as distinct from the schema it produces.

• Seeds, fixtures, projects/example/ and test/support/. The example overlay is a worked reference that tracks the core; it is not an API. Nor is core test support: test/support/ compiles only in the core's own :test env, and nothing in it — KilnCMS.FixturePlugin included — is a name your overlay may hold.

  One in-tree exception, which is not a pattern to copy. projects/example/project.exs restates KilnCMS.FixturePlugin in its :test plugin list. That is not the example depending on a fixture; it is the replace semantics of :plugins. config/test.exs registers the fixture plugin, config/project.exs is imported last, and an Elixir config list is replaced rather than merged — so activating the example inside this repository without restating it would deregister the plugin the core's own suite is written against. The example lives in the core's repo and is compiled by the core's :test env; your overlay is not, and has its own test suite. What does transfer is the mechanic: :plugins replaces, exactly as :ash_domains and :content_domains do, so every core entry you want kept has to be restated — and re-synced when you bump the pin.

• to_markdown/1 on a block module. KilnCMS.Blocks.to_markdown/1 calls it for the llm fired surface when a block module exports it, and falls back to the block's search_text/1 otherwise. It is probed with function_exported?/3, not declared on Kiln.Block.Renderer, and nothing tests an overlay block's implementation of it. Your block may define it, and the llm surface will use it today; a minor may rename or replace the probe.

• A hand-rolled @behaviour, when a callback is added. The use form inherits a default for every callback, so an addition is invisible to it. A module that declares @behaviour Kiln.Plugin (or any behaviour above) itself gets a missing-callback warning instead, which --warnings-as-errors turns into a failed build. Kiln.Plugin declares no optional callbacks at all, and Kiln.FieldType marks only its late additions optional. Hand-rolling is allowed (mix kiln.plugins.doctor accepts it); it is not protected against additions.

• Every other mix kiln.* task — the operator tasks (backfills, re-encryption, exports, imports, re-firing) and the developer ones — and the code mix kiln.gen.content and mix kiln.gen.plugin write, which is a starting point you own once it is generated. A release that needs you to run a task names it, spelled as it is in that release, in its upgrade notes.

What a minor may still do to you

Three things a minor is allowed to do that can still cost you work. None of them breaks compilation, which is why none of them is a major.

It may add migrations, including to the tables your content types project. The KilnCMS.CMS.Content macro contributes attributes to your resources, so a core migration that adds a column adds it to every overlay table too — and your tree carries its own migrations and snapshots, which the core's codegen cannot see. This has taken production down twice: a seo_keywords column (#452, fixed by #459) and a path_alias column (#488, fixed by #504), each time as undefined_column on the first request to a content API. The core's own overlay_drift CI job exists to catch exactly this against the in-tree example. Run its equivalent in your repo — see below.

It may add a callback to a behaviour. With use Kiln.Plugin you inherit a default for every callback, so an addition is invisible to you. A module that hand-rolls @behaviour Kiln.Plugin instead gets a missing-callback warning, which is an error under --warnings-as-errors. Use the use form; it is the documented path, and it is what keeps additions non-breaking.

It may change what a new install defaults to. Defaults are not data migrations: an existing deployment keeps its stored settings. Where a default changes in a way an operator should know about, the release carries an ### Upgrading note, and mix kiln.update prints it before moving your pin.

When a covered surface must change

Additive first, always: a new option, a new optional callback, a new function beside the old one. Where that is impossible:

1. Keep the old surface working for at least one minor, with the replacement documented beside it and a ### Deprecated entry naming both and the major that removes it.
2. Mark it deprecated where the compiler can carry the marker, so the warning reaches you at build time rather than in a changelog you skimmed: @deprecated on a function, a compile-time warning at your own use line for a macro option. Where the compiler cannot see the surface — a route, a stored row, a job already in the queue — the core logs a warning each time it is used (KilnCMS.Deprecations), and mix kiln.deprecations lists the data that still depends on it.
3. Remove it only in a major, with an ### Upgrade notes section that names the mechanical edit — what to rename, to what, and in which files.

A name is never silently repurposed. Reusing an existing option or callback name for different behaviour is the one change that defeats every check here, because it compiles.

Deprecated surfaces

The policy above was first used in 0.12 (#1537, #1538), and 1.0 removed what 0.12 deprecated (#1543).

Removed at 1.0

User.audiences itself is kept: no access decision reads it, but it is the only record of what a legacy account held, and billing still writes the cross-organization union there. 2.0 may drop the column.

Still deprecated

mix kiln.deprecations (in a release, bin/kiln_cms eval 'KilnCMS.Release.deprecations()') exits non-zero while this instance still holds data that only a removed surface read — accounts on the audiences fallback, or jobs in a pre-0.12 shape — so it can gate an upgrade to 1.0.

Protecting your overlay in CI

Four checks, but they do not all run in the same place — two need more than a source tree, which is the detail that makes people skip them.

On every build, with your config/project.exs in place and your overlay's priv/ merged, exactly as the image build does it:

mix ash.codegen --check     # the core's overlay_drift job, run against you
mix kiln.plugins.doctor     # domains registered, no name collisions

Without the activation step the first one checks the core alone: it passes while your tables drift, which is the failure it exists to catch.

Against a migrated database — post-deploy, or in a job with Postgres, as it inspects the live schema rather than your source:

mix kiln.search.check       # every content type has its search-vector migration

From inside your pinned Kiln checkout, not your overlay repo — the task refuses to run anywhere else, and it fetches from the network unless you pass --no-fetch:

mix kiln.update --check --exit-code

Pin to tags rather than a branch. mix kiln.update --ref main deliberately skips both the version comparison and the upgrade notes, so tracking main means opting out of every guarantee on this page.

Known soft spots

Stated rather than discovered later.

• The block upcast path has run once, on one step. heading is at version 2, and mix kiln.blocks.backfill (#1537) rewrites stored blocks through the same migrate chain the lazy read uses — tested against a corpus of every stored shape (test/support/legacy_block_corpus.ex), not yet against a large production archive. A missing migrate step is a compile warning (Kiln.Block.MigrationChain; an error from Kiln 2.0), and a stored block behind the gap is refused — left as stored, _version included — rather than stamped current; KilnCMS.Blocks.Upcaster.try_upcast/2 says why. If your overlay versions a block, add the stored shapes it replaces to a corpus like that one, and run the backfill with --dry-run first.
• Upcasting is lazy until you run the backfill. Stored blocks behind the head version are upcast on every read, and rewritten on disk only by mix kiln.blocks.backfill, which you run — nothing schedules it. Either way, already-fired artifacts need re-firing (mix kiln.refire_all) after a block's shape changes.
• Rows written before the typed block storage are converted on read until the backfill has run. The tolerant read stays after 1.0 — for the rows the backfill reports rather than rewrites, and for version history, which is hash-chained and keeps being read in whatever shape it was written. A block of a type this build no longer has, or an element that is not a block, reads as a custom block carrying its payload, so delivery never fails on it. Only the legacy write shape was removed at 1.0 (#1543).
• to_markdown/1 on a block module is probed informally, not declared on the renderer behaviour. Treat it as unstable until it is.
• The hand-rolled @behaviour path is fragile against additions, on every behaviour here. Kiln.Plugin declares no optional callbacks at all, and Kiln.FieldType marks only its three late additions optional — the rest are required-but-defaulted, exactly like Kiln.Plugin's. So a module that declares @behaviour instead of using the use form gets missing-callback warnings when a callback is added, which --warnings-as-errors turns into a failed build. The use form is what makes additions safe; prefer it.

Status of this document

From 1.0.0 this page is the definition of what a major bump means — and the reason a major is rare rather than routine. Removing a covered surface, or changing what one means, takes a major release and goes through the deprecation path above; adding one does not.