Skip to content

Release process#

How a change goes from merged-to-master to published. Pre-1.0; will tighten at 1.0.

Release cadence#

  • Minor (0.11 → 0.12) — quarterly
  • Patch (0.11.0 → 0.11.1) — as needed (security / critical bugs)
  • LTS — annually (year-end), tagged v2026.x

See Deployment: Upgrade & versioning.

Who cuts a release#

Today: the founder-maintainer. Post-v1.0: two-maintainer sign-off.

Pre-release checklist#

Before the release PR:

  • All CI green on master for the last 3 commits
  • Full regression + bench green (local)
  • CHANGELOG.md updated with a new section for this version
  • Breaking changes documented in the changelog with migration notes
  • Version bumped in ml_team/pyproject.toml, ml_team/dashboard/package.json, ml_team/api/app.py
  • docs/content/reference/changelog.md verified to include the new release
  • Security advisories, if any, finalised and timed to coincide
  • ADR written for any new architectural decision in .project/decisions.md

The release PR#

# Branch
git checkout -b release/0.12.0

# Bump versions (single commit)
# ... edit 3 files + CHANGELOG

git commit -s -m "chore(release): 0.12.0"

# Push + open PR
git push origin release/0.12.0
gh pr create --title "Release 0.12.0" --body "$(cat .github/release-pr-template.md)"

CI runs; maintainer reviews; squash-merge when green.

Tag + publish#

After the release PR merges:

git checkout master
git pull

# Create annotated tag at the release commit
git tag -a v0.12.0 <commit_sha> -m "v0.12.0 — <one-line summary>"

# Push the tag
git push origin v0.12.0

CI workflow .github/workflows/release.yml detects the tag and:

  1. Builds + publishes Python wheel to PyPI (swarm-agent)
  2. Builds + pushes Docker images to ghcr.io/theaisingularity/swarm-api:0.12.0 + ...swarm-dashboard:0.12.0
  3. Signs images with cosign
  4. Publishes Helm chart to the swarm chart registry
  5. Creates a GitHub Release with auto-generated notes
  6. Announces on mailing list + social

All of these are idempotent — re-running the workflow is safe.

LTS release#

Annually (year-end), we pick a current minor and tag it as the LTS:

git tag -a v2026.1 <commit_sha> -m "v2026.1 LTS"
git push origin v2026.1

LTS branches: - Created from the LTS commit (git checkout -b lts-2026.1 v2026.1) - Receive security-only patches for 24 months - Patches shipped as v2026.1.N - Backports happen manually from master

Security release#

For CVE fixes, abbreviated process:

  1. Fix lands in a private security-advisory branch
  2. Tested privately against current minor + LTS
  3. Coordinated disclosure window set
  4. At disclosure time: tag both patched versions, publish, announce simultaneously
  5. Public advisory at GitHub Security Advisories + SECURITY.md

Release notes template#

Auto-generated from conventional commits. Manual edits to add:

  • Upgrade guide (any breaking changes)
  • Highlights (3-5 notable features)
  • Known issues (if any)
  • Thanks (external contributors)

Template:

# v0.12.0 — <theme name>

## Highlights

- <headline feature 1>
- <headline feature 2>
- <headline feature 3>

## Breaking changes

- <change> — **migration:** <what to do>

## Features

<list from CHANGELOG>

## Bug fixes

<list from CHANGELOG>

## Upgrade guide

1. <step>
2. <step>

Full diff: <link>.

## Thanks

- @contributor1 — <contribution>
- @contributor2 — <contribution>

## Known issues

<if any>

Artifact verification#

Downstream users should verify signatures:

# PyPI wheel signature
pip install sigstore
python -m sigstore verify identity \
  --cert-identity https://github.com/TheAiSingularity/swarm/.github/workflows/release.yml@refs/tags/v0.12.0 \
  --cert-oidc-issuer https://token.actions.githubusercontent.com \
  swarm-agent-0.12.0-py3-none-any.whl

# Docker image signature (cosign)
cosign verify ghcr.io/theaisingularity/swarm-api:0.12.0 \
  --certificate-identity-regexp "^https://github.com/TheAiSingularity/swarm/" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

What if we ship something broken#

The docs-deploy.yml and release.yml both ship the version — if broken:

  1. Patch ASAP — backport the fix to the current minor + LTS, tag as 0.12.1
  2. Delete nothing — don't remove the broken version from PyPI; pin old, urgent pip install swarm-agent==0.12.1
  3. Announce — mailing list + status page + customer CSM
  4. Post-mortem — blameless, within a week, published

Pre-1.0 caveats#

At pre-1.0: - Minor versions may include breaking changes (flagged explicitly) - API stability guarantees kick in at v1.0 - LTS backport support starts at v2026.1

Next#