include::{mod-loc}shared/all-attributes.adoc[]

[id="versioning-support-policy_{context}"]
= Versioning and support policy

[role="_abstract"]
This chapter describes the {registry} versioning scheme, support policy, release channels, and guidance for upgrading and handling rollbacks.

* xref:versioning-scheme_{context}[]
* xref:support-window_{context}[]
* xref:release-channels_{context}[]
* xref:upgrading-registry_{context}[]
* xref:downgrades-and-rollbacks_{context}[]


[id="versioning-scheme_{context}"]
== Versioning scheme

[role="_abstract"]
{registry} follows https://semver.org/[Semantic Versioning] with a clear distinction between minor and patch releases.

[cols="1,2,2", options="header"]
|===
| Release type
| Contents
| Example

| *Minor* (e.g., 3.3.0 -> 3.4.0)
| New features, enhancements, and bug fixes
| Scheduled development milestones

| *Patch* (e.g., 3.3.0 -> 3.3.1)
| CVE and security fixes only
| Dependency upgrades, security patches
|===

Patch releases do not contain new features or bug fixes.
They are limited to changes that address known security vulnerabilities.


[id="support-window_{context}"]
== Support window

[role="_abstract"]
{registry} maintains the *two most recent minor versions* with security patches.

When a new minor version is released, the oldest supported minor version reaches end-of-life and no longer receives updates.

.Example support timeline
[cols="1,1,1", options="header"]
|===
| Event
| Supported versions
| End-of-life

| 3.3.0 released
| 3.3.x, 3.2.x
| 3.1.x and older

| 3.4.0 released
| 3.4.x, 3.3.x
| 3.2.x and older
|===


[id="release-channels_{context}"]
== Release channels

[role="_abstract"]
{registry} provides multiple release channels so that you can choose the update cadence that suits your deployment.


=== Docker image tags

[cols="1,3", options="header"]
|===
| Tag
| Description

| `3.3.0`
| Pinned to an exact release. Never changes.

| `3.3`
| Floating tag that always points to the latest patch in the 3.3.x series (e.g., 3.3.0 -> 3.3.1 -> 3.3.2).

| `latest` / `latest-release`
| Always points to the most recent stable release across all minor versions.

| `latest-snapshot`
| Most recent build from the `main` branch. Unstable and not recommended for production.
|===

Use the minor-series floating tag (e.g., `3.3`) to automatically receive security patches without upgrading to a new minor version.


=== OLM channels (Kubernetes operator)

If you deploy {registry} using the {operator}, each minor version has its own OLM channel:

[cols="1,3", options="header"]
|===
| Channel
| Description

| `3.3.x`
| Receives only patch updates within the 3.3 minor version.

| `3.x`
| Rolling channel that always tracks the latest minor version.
|===

Subscribe to a minor-version channel (e.g., `3.3.x`) for stability, or to the `3.x` rolling channel to always receive the latest features.


[id="upgrading-registry_{context}"]
== Upgrading {registry}

[role="_abstract"]
{registry} supports forward upgrades.
Database schema migrations run automatically on startup and do not require manual intervention.

[IMPORTANT]
====
Always back up your database before upgrading to a new minor version.
See xref:backup-before-upgrade_{context}[].
====


=== Patch upgrades (within a minor version)

Patch upgrades (e.g., 3.3.0 -> 3.3.1) are safe and always recommended.
They contain only CVE fixes and do not introduce behavioral changes.

.Procedure
. Back up your database.
. Replace the {registry} container image with the new patch version or use the minor-series floating tag.
. Start {registry}. Any required schema migrations run automatically.


=== Minor upgrades

Minor upgrades (e.g., 3.3.x -> 3.4.0) include new features, enhancements, and bug fixes.

.Procedure
. Review the release notes for the target version to understand new features and any behavioral changes.
. Back up your database.
. Replace the {registry} container image with the new minor version.
. Start {registry}. Database schema migrations run automatically.
. Verify that your client applications work correctly with the new version.


=== Skipping minor versions

Upgrading across multiple minor versions (e.g., 3.2.x -> 3.4.x) is supported.
Database migrations are cumulative and applied in order on startup.

Review the release notes for all intermediate versions to understand the full set of changes.


[id="downgrades-and-rollbacks_{context}"]
== Downgrades and rollbacks

[role="_abstract"]
{registry} does *not* support downgrades.

Database schema migrations are forward-only and irreversible.
Starting an older version of {registry} against a database that has been migrated to a newer schema version will fail.

If you deploy {registry} using the {operator}, switching to an older OLM channel is also not supported.

=== Handling a failed upgrade

If an upgrade introduces issues, restore from the database backup taken before the upgrade:

.Procedure
. Stop {registry}.
. Restore the database from the backup taken before the upgrade.
. Deploy the previous version of {registry}.
. Investigate the issue before attempting the upgrade again.

Do *not* attempt to manually revert database schema changes.


[id="backup-before-upgrade_{context}"]
== Backing up before an upgrade

[role="_abstract"]
Before any minor version upgrade, create a backup of your {registry} database.

For PostgreSQL deployments:

[source,bash]
----
pg_dump -h <host> -U <username> -d <database> -F c -f registry-backup-$(date +%Y%m%d).dump
----

For KafkaSQL deployments, back up both the Kafka topic data and the SQL snapshot database.

Store backups in a secure location and verify that they can be restored before proceeding with the upgrade.


[role="_additional-resources"]
.Additional resources
* xref:registry-migration_{context}[Migrating from {registry} {registry-v2} to {registry} 3.x]
