Versioning & Deprecation

What a version number promises, and how things are retired. This page is policy, not aspiration — where it claims a mechanism, the mechanism exists and is cited.

Version numbers

PRISM follows semantic versioning on the surfaces an operator can touch:

• Major (2.0.0): something you depend on changed shape — a config key removed, an admin endpoint's contract changed, a metric renamed, a default whose change alters behaviour you tuned.
• Minor (1.5.0): new capability; every existing config keeps parsing and every tuned behaviour stays tuned. Defaults may change where the old default was a defect — each such change is called out in the release notes' Upgrading section.
• Patch (1.4.2): fixes. No new keys, no changed defaults.

The versioned surfaces are: the config schema, the admin API, response headers, metric names and labels, package/repository layout, and the container image's entrypoint contract. Internal Rust APIs are not a versioned surface — PRISM is a product, not a library.

The deprecation contract

1. Nothing disappears within a major. A key slated for removal keeps parsing for the remainder of the major version.
2. Deprecated things warn at startup, naming their replacement. The pattern already operates today: the [detect] section is accepted for backwards compatibility, does nothing at runtime, and says so at startup (startup_warnings in the config module) — that is the shape every future deprecation takes.
3. Removal happens at the next major, listed in that release's Upgrading notes with the exact replacement.
4. Unknown keys are still errors. PRISM refuses configs with unknown fields (deny_unknown_fields) so a typo cannot silently disable the thing it misspells. Deprecation never loosens this: deprecated keys are known keys.

How often a release happens

A version number is cheap to mint and impossible to withdraw. Release tags here cannot be deleted or moved — the ruleset refuses deletion, update and non_fast_forward with no bypass — so every number is permanent, and a stream of them costs an operator attention on every one.

Between 22 August and 1 September 2026, eight tags were cut. Each had a defensible reason. That is exactly the failure mode: "this one is justified" is true of every release in a run of eight, and the reasons never run out.

So a release needs two things, not one:

1. A reason — something an operator must receive: a defect affecting deployments that work today, or a body of work that is finished.
2. A gap — at least two weeks since the last tag, unless the reason is a defect that is live in what people are running right now.

The second is what the first cannot supply on its own. A fix that is real but not urgent waits on main under ## Unreleased, where it costs nothing and accumulates into a release worth reading.

The exception is narrow and named: a defect present in the published artifacts, affecting installations that exist. 1.5.2 qualified — the shipped systemd unit made the binary warn about itself on first start. Most fixes do not, however satisfying it is to ship them.

Release record

The changelog is the release record; each release's Upgrading section is the migration guide. It is generated from CHANGELOG.md in the repository, so the page you are reading and the file the maintainers edit are the same text. There are no GitHub Releases — packages come from the repositories, images from the registry, and each release's SBOM and checksums live at pkg.trident-cache.com/prism/provenance/<tag>/.

Support window

Security fixes land in the current series only; older series are upgrades, not backport targets. The table in SECURITY.md is the authority and says the same thing — if these two ever disagree, SECURITY.md wins and this page is the bug.

What this policy does not promise

• Byte-identical rendered output across versions — Chromium moves under a documented update SLA (see SECURITY.md), and rendering follows it.
• Stability of log message wording. Log fields used by the shipped ops pack are treated as a versioned surface; prose is not.