Skip to content
SupaCloud Docs
Select themeSelect language

Cut a release

This is the standard operating procedure for cutting a SupaCloud release. SupaCloud follows Semantic Versioning and the Keep a Changelog format. CHANGELOG.md at the repository root is the single source of truth for the public, human-readable changelog rendered on the marketing site’s /changelog page (en + de) — it is synced into the site at build time (ADR 0045).

When to add a changelog entry

Section titled “When to add a changelog entry”

Add an entry whenever a change is user-visible: a new feature, a behaviour change, a fix users would notice, or a security-relevant change. Internal refactors, test-only changes and CI plumbing do not need an entry.

The changelog-gate CI workflow enforces this: a pull request that touches web/, marketing/src/ or docs/{user,admin}/ must also touch CHANGELOG.md.

Steps

Section titled “Steps”

  1. Add your change under ## [Unreleased] (or the pending version section) in CHANGELOG.md, in the right category — Added, Changed, Deprecated, Removed, Fixed, or Security. Write it for users, not for the commit log.

  2. Re-sync the marketing homepage. The /changelog page renders a generated module synced from CHANGELOG.md, fingerprinted by a committed drift lock:

    Terminal window
    cd marketing
    npm run sync:changelog        # regenerate the module + refresh changelog.lock
    npm run changelog:check        # confirm the drift hash matches (CI runs this)

    Commit the refreshed marketing/src/lib/generated/changelog.lock (the full generated module is gitignored — the lock is the drift contract).

  3. At release time, bump the version. Promote ## [Unreleased] to ## [X.Y.Z] - YYYY-MM-DD (keep an empty ## [Unreleased] above it for the next cycle) and update the compare links at the foot of the file. Pick the bump per SemVer: breaking → MAJOR, additive → MINOR, fix-only → PATCH. Then re-run the sync from step 2 so the lock reflects the dated section.

  4. Verify locally before tagging:

    Terminal window
    cd marketing && npm run check && npm run build
    npx --yes markdownlint-cli2 --config .markdownlint.jsonc CHANGELOG.md

  5. Open the release PR with the version bump + the lock change. CI runs changelog-gate (section present, drift check, markdownlint) plus the normal build-push gates.

  6. Tag after merge. Once the PR is on main:

    Terminal window
    git tag -a vX.Y.Z -m "vX.Y.Z"
    git push origin vX.Y.Z

    The build-push pipeline builds and signs the server / web / marketing images for that commit; the marketing image bakes in the freshly-synced /changelog.

See also

Section titled “See also”