Deprecation policy

View as Markdown

This page defines how Registry Stack retires surface covered by the compatibility promise: the notice a deprecation gives, where it is announced, and what a removal must ship with. It takes effect at v1.0.0; before that, breaking changes follow the pre-1.0 rule and are announced with BREAKING: entries and migration steps in stack release notes, plus an owning product CHANGELOG where one exists.

The lifecycle of a covered element

A covered element (route, field, error code, config key, CLI flag, artifact name) moves through three states:

Active. The element is documented and supported.
Deprecated. The element remains compatible, and its replacement is available and documented. Deprecation happens in a minor release.
Removed. The element is gone. Removal happens in a major release, and no earlier than 6 months after the release that announced the deprecation.

Except for a documented security removal, nothing skips the deprecated state. A covered element that exists in v1.0.0 or is added later is never removed without a deprecation release first.

How a deprecation is announced

A deprecation is announced in every channel a consumer of that element reads:

The release note for the announcing release, under release/notes/, gains a Deprecated entry naming the element, the replacement, and the earliest release that may remove it. Products that keep their own CHANGELOG (Registry Manifest and the platform crates) carry the same entry there.
An HTTP route or field that a committed OpenAPI document for a covered surface describes is marked deprecated: true in that document. Evidence Gateway currently has the only such document. The committed OID4VCI supporting-service document remains exempt until that service enters the covered-surfaces table. Relay publishes no product-level document, so a Relay route deprecation is announced in the release note and marked on the reference page for the route inventory instead.
A config key or authoring-grammar key that is renamed keeps working through the deprecation window. Relay’s registry.yaml and runtime.yaml grammars reject unknown keys, so the removal release turns the retired key into a startup refusal rather than a silently ignored field, and the release note carries the replacement name.
A Rust-level #[deprecated] attribute marks internal APIs where relevant. Precedent: verify_jsonl_lines and CorsPolicy::layer() in products/platform/CHANGELOG.md.
The docs page that documents the element gains a note with the since vX.Y convention, naming the replacement.

Migration notes are mandatory

Every deprecation and every removal ships with concrete migration steps in the entry that announces it: old key to new key, old route to new route, old metric name to new metric name, with copyable examples. “Removed X” without a migration path does not meet this policy. For examples, read the BREAKING: entries in release/notes/v0.19.0.md, which name the replacement binary for each retired one and state that a Relay 1.0 configuration is not an in-place upgrade input.

A removal that has no migration path is a different event, and this policy does not let a release disguise one as a rename. The v0.19.0 replacement of Relay 1.0 and registryctl says so in those words: the replacement requires a new governed Registry contract rather than a conversion of the old configuration. See Relay V1 and registryctl retirement.

Security exceptions

A fix for a vulnerability may tighten or remove surface without the full notice period when keeping the surface functional would keep deployments exploitable. The release notes document the security removal, the shortened window, and migration steps without disclosing information that would put unpatched deployments at additional risk.

What this policy does not govern

Documentation pages have their own lifecycle. A docs page with frontmatter status: deprecated is a superseded page, not a scheduled API removal. The two uses of the word are unrelated.
Pre-1.0 history is not retroactively bound. Renames and replacements executed before v1.0.0 predate this policy: the 2026-05-23 product rename was a clean break with no aliases, and the v0.19.0 replacement of the Relay 1.0 runtime and registryctl shipped as a breaking product replacement with no deprecation window and no migration path from the old configuration. Neither is a precedent for what a covered element gets after v1.0.0.
Exempt surfaces listed in the compatibility promise can change without deprecation notice.