Versioning¶

Vesana follows semver with clear rules.

Schema¶

MAJOR.MINOR.PATCH

Bump	What happens	Rollback possible?
Patch (0.19.0 → 0.19.1)	Bug fixes, no schema changes	Yes, free
Minor (0.18.x → 0.19.0)	New features, additive migrations	Yes, conditionally
Major (0.x.y → 1.0.0)	Breaking changes after deprecation	No

Version format¶

v prefix in tags and VERSION files: v0.19.0, not 0.19.0.

In API responses (X-Vesana-Version) and frontend build it's the bare value without v.

Migrations¶

Additivity¶

Migrations may:

create new tables
add new columns (with DEFAULT or NULLABLE)
create new indexes
seed new builtin data via UPSERT

In a minor, migrations may not:

drop columns
drop tables
introduce NOT NULL without default
rename existing columns
run data operations destroying existing values

Destructive changes belong in a major migration with deprecation lead.

Example deprecation¶

v0.19.0 — agent_managed column marked deprecated (code stops writing, still reads)
v0.20.0 — code stops reading, column stays
v1.0.0 — migration drops the column

At least 2 majors between „no longer used" and „dropped".

Rollback window¶

Within a minor, rollback is free. Example:

0.19.3 → 0.19.4 → 0.19.5 — all rollback-able
0.19.5 → 0.20.0 — rollback conditionally, new columns stay empty

For majors: no rollback. Backup first, test first.

Auto-update behavior¶

The GUI updater has a channel:

Channel	What it installs
`stable` (default)	only stable releases (vetted, documented)
`beta`	release candidates before stable
`pinned:vX.Y.Z`	only this exact version, no auto-update

Set in .env: VESANA_UPDATE_CHANNEL=stable.

Pre-release tags¶

Tag	Meaning
`0.19.0-rc.1`	Release candidate
`0.19.0-beta.1`	open testers
`0.19.0-dev`	unstable, not for production

stable channel skips pre-releases.

Breaking changes — policy¶

Not every change is breaking. The definition:

Breaking is a change that causes:

existing API clients with identical code to error
existing agents/collectors to stop working
existing configs to become invalid without migration

Non-breaking:

new optional fields
new endpoints
more detail in error responses
new UI paths
new permissions (default roles get them automatically)

For breaking: major release, deprecation phase at least one minor before, migration guide in changelog.

API versioning¶

/api/v1/ is stable. If /api/v2/ came, it would:

run parallel to v1 for at least 2 majors
v1 endpoints would send Deprecation header
migration docs per endpoint

Currently only v1 in sight.

Frontend versioning¶

Frontend bundle deploys with each server update. No API version binding — frontend always uses v1.

For larger frontend changes: cache buster in build hash, old tabs show a „please reload" banner.

Agent / collector versioning¶

Agent / collector have own versions independent of the server. Auto-update brings them to the server-published VERSION.

Compatibility: any agent/collector ≥ previous major release should be compatible with any server. Older versions report with warning but still work.

How we release¶

flowchart LR
    DEV[Feature PR]
    DEV --> MERGE[Merge to main]
    MERGE --> CI[CI: tests + build]
    CI --> TAG[git tag v0.X.Y]
    TAG --> RELEASE[GitHub release with notes]
    RELEASE --> GHCR[Image push GHCR]
    GHCR --> LP[License portal published]
    LP --> END[Self-hosters see update banner]

Per release: detailed notes, migration hint if relevant, breaking changes (for majors) prominently at top.

How we handle hotfixes¶

For critical bugs:

Patch branch from last stable tag
Fix commit
vX.Y.(Z+1) tag
Quick release without waiting for next planned update
GUI updater shows availability immediately

Hotfixes are explicitly marked in the changelog ((hotfix)).