Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/v/0.38.0/llms.txt
Full corpus: https://docs.registrystack.org/v/0.38.0/llms-full.txt

# Deprecation policy

> How Registry Stack retires covered surface, the notice operators get, and the migration notes every removal carries.

This page defines how Registry Stack retires surface covered by the
[compatibility promise](../api-stability/): 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:

1. Active. The element is documented and supported.
2. Deprecated. The element remains compatible, and its replacement is available
   and documented. Deprecation happens in a minor release.
3. 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](../../decisions/relay-v1-and-registryctl-retirement-2026-08-11/).

## 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](../api-stability/) can change without
  deprecation notice.

## Next

- [API stability and versioning](../api-stability/)
- [Security support window](../../security/support-window/)
- [Errors and status codes](../errors/)