Skip to content

Upgrade & versioning#

Release cadence, LTS policy, breaking-change process, migration paths.

Release cadence#

Release type Frequency Example
Minor (0.11 → 0.12) Quarterly 0.12 ships ~July 2026
Patch (0.11.0 → 0.11.1) As needed (security / critical bug) Within days of report
LTS Annually, designated at year-end v2026.1 (likely based on 0.14 or 0.15)

Versioning rules#

  • Semantic versioning where possible. Pre-1.0 (current), minors may include breaking changes, but each is flagged in release notes.
  • No breaking changes in patches. Ever.
  • Deprecation period for breaking changes: at least 6 months, counted from the release the deprecation was announced in.
  • Feature flags gate experimental surfaces. Breaking changes to experimental surfaces are exempt from the 6-month rule.

LTS policy#

One LTS released per year:

  • Active support — security + critical-bug patches for 12 months after GA
  • Security-only — security patches for another 12 months (total 24 months)
  • EOL — no further patches; upgrade mandatory for continued support

LTS versions always have a year prefix (v2026.1, v2027.1). Only one LTS is supported at a time after the second year.

Upgrade paths#

Patch (0.11.0 → 0.11.3)#

Drop-in. No config changes. No data migrations.

# Docker Compose
docker compose pull
docker compose up -d

# Helm
helm upgrade swarm swarm/swarm --reuse-values --version 0.11.3

Minor (0.11 → 0.12)#

May require: - Config changes (new fields, renamed env vars) - Data migration (DB schema) - Behaviour changes behind feature flags

Release notes always list what you need to do.

# Always back up first
kubectl -n swarm exec -it <postgres-pod> -- pg_dump > backup-pre-0.12.sql

# Check migration guide
open https://docs.theaisingularity.org/reference/changelog

# Upgrade (atomic — rolls back on failure)
helm upgrade swarm swarm/swarm --version 0.12.0 --atomic --timeout 10m

# Verify
kubectl -n swarm get pods
curl https://swarm.customer.com/api/v1/healthz

Major (0.x → 1.0, 1.x → 2.x)#

Reserved for fundamental API breaks. When this happens: - At least 12 months of deprecation notice - Migration tool provided (swarm migrate --from 0.x --to 1.0) - Parallel-run support — old + new versions can run side-by-side for N days - Written upgrade guide with concrete before/after examples

We don't plan to break this way frequently. Expect 1.0 in ~12-18 months from 0.11.

DB migrations#

Managed automatically by the Helm chart (via a migrate-on-upgrade Job) or by Docker Compose on restart.

Manual invocation (rare):

# From inside the api container
swarm migrate upgrade

# To inspect what would run:
swarm migrate check

# To roll back one step:
swarm migrate downgrade -1

Migrations use Alembic (SQLAlchemy's migration tool). Scripts in ml_team/api/migrations/.

Rollback#

Patch / minor#

# Helm
helm rollback swarm <previous-revision>

# Docker Compose
docker compose pull swarm:<previous-version>
docker compose up -d

Data caveat: rolling back a DB migration that added a required column is risky. Prefer forward fix (release another patch) over rollback when data migrations are involved.

Bad release (we published broken software)#

Highest-severity scenarios:

  1. Security patch released — always roll forward; we will publish an advisory
  2. Breaking regression in a minor — we'll publish a patch within 7 days; roll back to previous minor in the meantime
  3. Data corruption — stop writes immediately, restore from backup, contact us at security@theaisingularity.org

Feature flag deprecation#

Flags move through tiers as features mature:

Experiment → Flag → Invariant
    │          │         │
    │          │         └─ cannot be disabled (regulatory / safety invariant)
    │          └─ production default, operator-toggleable
    └─ opt-in, may change or disappear

Moving up a tier is announced one minor version in advance. Moving down is rare and always backwards-compatible.

Skew support#

When upgrading a multi-replica deployment, old and new versions run side-by-side briefly during a rolling update.

Component pair Supported skew
api ↔ api ±1 minor (e.g. 0.11 + 0.12)
api ↔ dashboard ±1 minor
api ↔ database schema exact match within patch; +1 ahead for minor
cron / batch workers match api version

Breaking-changes index (per version)#

0.10 → 0.11 (current)#

  • python-jose replaced by authlib.joserfc — no user-visible change; fixes CVE
  • plugin_shell_hooks_enabled feature flag added (default off) — no existing behaviour changes
  • plugin_commands_enabled, plugin_agents_enabled flags added (default on) — new capabilities, no breaks
  • install_drops_json column added to plugins table — transparently migrated

0.11 → 0.12 (planned)#

Expected breaking changes: - Managed SaaS multi-tenant API — changes base path from /api/v1 to /api/v1/t/{tenant_id} for multi-tenant mode (self-hosted unchanged) - SWARM_DB_URL is mandatory for multi-replica deployments (was optional in 0.11 with SQLite fallback) - Environment variable renames (announced in advance)

0.12 → 1.0 (12+ months out)#

  • Final API stability freeze
  • All deprecated flags removed
  • Semver strictly enforced

Communication channels#

Where breaking changes are announced:

  • CHANGELOG.md — authoritative
  • Mailing list: swarm-announce@theaisingularity.org (opt-in)
  • GitHub Releases — every tag has notes
  • Enterprise customers — written notification 60 days before breaking minors, 6 months before breaking majors

Subscribing#

# RSS / Atom feed of releases
curl https://github.com/TheAiSingularity/swarm/releases.atom

# GitHub watch → Releases only
# gh repo edit --subscribe

Next#