User Guide

Deprecations

View as Markdown

Every active AICR deprecation, the replacement, and the release that removes it. An entry stays on this page until the removal ships, then moves to Removed for one further release so an operator upgrading across several versions can still find out what happened.

The policy behind this page — what counts as a breaking change on each surface, and the notice a removal owes — is in RELEASE.md.

How you will find out

You do not have to read this page to be warned. Every deprecation is announced on the affected surface through that surface’s own channel — which is not always a runtime warning, because the most useful moment to be told differs by surface:

SurfaceWhat you seeWhen
CLIA warning on stderr naming the replacement and the removal releaseAt run time
RESTA Deprecation header (RFC 9745) with the deprecation date, a Sunset header (RFC 8594) with the removal date, a Link with rel="deprecation", and deprecated: true on the operation in the OpenAPI specOn every response
Go SDKA // Deprecated: godoc marker, which staticcheck reports as SA1019At build time
Bundles and artifactsA loader warning naming the file and the release that stops reading itWhen the artifact is read

The Go SDK is deliberately build-time rather than run-time: the compiler and your linter can tell you before you ship, which beats a log line from production.

That announcement is the contract. If something was removed without one, that is a bug worth filing.

Active

Alpha artifact apiVersion values

Surface: bundle and artifact schemas · Deprecated in: v0.22 · Removed in: v0.23

Every artifact AICR generates carried an alpha apiVersion — aicr.run/v1alpha2 for most kinds, aicr.run/v1alpha3 for profile-bearing recipes. Those values are being replaced by maturity-appropriate targets, per ADR-022.

KindRetiringReplacement
Snapshot, default RecipeResult, RecipeCriteria, BundleProvenanceaicr.run/v1alpha2aicr.run/v1
AICRConfig, catalog RecipeMetadata, RecipeMixin, ComponentRegistryaicr.run/v1alpha2aicr.run/v1beta1
Profile-bearing RecipeMetadata and RecipeResultaicr.run/v1alpha3aicr.run/v1beta2

What to do. Generated artifacts — snapshots, resolved recipes, bundle provenance — are recaptured or regenerated by re-running the command that produced them. Files you authored — AICRConfig, and any external RecipeMetadata, RecipeMixin, or ComponentRegistry in a --data catalog — are edited by hand. AICR has no conversion layer and does not rewrite your catalog.

The window is v0.22 only. v0.21 and v0.22 read both the alpha and the target values; v0.23 reads only the target. An archived artifact whose source cannot be recaptured stays readable only with a retained v0.21 or v0.22 binary. See catalog and binary compatibility for the release-by-release table.

Empty apiVersion on artifacts

Surface: bundle and artifact schemas · Deprecated in: v0.22 · Removed in: v0.23 for RecipeResult inputs; already removed in v0.21 for RecipeMetadata overlays

Artifacts predating the apiVersion field load today with the field absent or empty. That tolerance retires alongside the alpha values — except for RecipeMetadata, which lost it a release early and without a warning window; see below.

One narrowing landed earlier than the rest: as of v0.21, a RecipeMetadata overlay passed directly (aicr bundle -r overlay.yaml, aicr validate -r overlay.yaml) must carry an apiVersion, because the catalog scanner already required one and the two paths disagreed on the same bytes (#2421). Hydrated RecipeResult inputs keep the tolerance until v0.23.

What to do. Add an apiVersion header to any artifact you author or retain. Use the target value from the table above, not the alpha one — v0.21 onward accepts both, and only the target survives v0.23.

Removed

Nothing has completed a removal cycle yet. The first entries land in v0.23.