Versioning & Releases

UDS Core follows Semantic Versioning 2.0.0 with a predictable two-week release cadence.

Release cadence

Minor/major releases are published every two weeks (typically on Tuesdays).
Patch releases are cut outside the regular cycle for critical issues that cannot wait.

Patches are reserved for:

Bugs preventing installation or upgrade (even for specific configurations)
Issues limiting access to core services (UIs/APIs) or ability to configure external dependencies
Significant regressions in functionality or behavior
Security vulnerabilities requiring immediate attention

Semantic versioning

UDS Core is not a traditional library; its public API is defined by the surfaces that users and automation interact with:

Surface	Examples
CRDs	Schema fields, types, validation rules, operator behavior
Configuration and packaging	Config chart values, exposed Zarf variables, component organization and included components in published packages
Default security posture	Network policies, service mesh config, runtime security, mutations and validations

Anything not listed above (internal Helm templates, test utilities, unexposed implementation details) is not part of the public API. See the full versioning policy for the complete definition and examples.

Breaking vs non-breaking changes

Breaking changes are documented in the CHANGELOG under the ⚠ BREAKING CHANGES header and in GitHub release notes. Each entry includes upgrade steps when applicable.

In general:

Major version bump: removal, renaming, or behavioral change to any public API surface; changes to defaults that alter existing behavior
Minor version bump: new opt-in features, additive CRD fields, new CRD versions without removing the old
Patch version bump: bug fixes restoring intended behavior, performance improvements with no behavioral change

See the versioning policy for the full breakdown and examples of each category.

Version support

UDS Core provides patch support for the latest three minor versions (current plus two previous). Minor and major releases are cut from main, while patch releases are published from dedicated release/X.Y branches.

Patch releases follow the patch policy and are documented in GitHub releases, not the main repository changelog.

Deprecation policy

Deprecations signal upcoming breaking changes and give users a predictable migration window before removal.

How deprecations are announced

Deprecations use the feat(deprecation) conventional commit format and appear in GitHub release notes. Each deprecation includes:

What is being deprecated and why
The recommended replacement or migration path
The projected major version in which it will be removed

All active deprecations are tracked in DEPRECATIONS.md.

Support period

Deprecated features remain supported for at least three subsequent minor releases and may only be removed in a major release. During the support period they continue to function without behavioral changes and may receive bug and security fixes.

Example: A feature deprecated in 1.3.0 must remain supported through 1.4.0, 1.5.0, and 1.6.0. It becomes eligible for removal starting in 2.0.0 (assuming 2.0.0 is released after 1.6.0).

CRD guarantees

CRDs are a primary API boundary and follow Kubernetes API deprecation conventions with stability tiers:

Alpha CRDs (e.g., v1alpha1) may change or be removed without a deprecation period
Beta and GA CRD fields and versions remain accepted for at least three minor releases before removal
New CRD versions may be introduced without removing older versions
CRD version or field removal only occurs in major releases (for beta/GA)

See ADR 0008 for full CRD versioning and conversion details.

Development builds

Nightly snapshots

Automated builds from the latest main branch are created daily at 10:00 UTC:

Tagged as snapshot-latest on GitHub
Available as Zarf packages and UDS bundles in the GitHub Packages repository
Each snapshot is tagged with a unique identifier combining date + commit hash + flavor (e.g., 2026-03-18-9496bfe-upstream); the most recent snapshot for each flavor is also tagged latest-<flavor> (e.g., latest-upstream, latest-registry1)

Feature previews

For significant new features or architectural changes, special snapshot builds may be created from feature branches or main for early feedback and validation.