Skip to content

Releases and versioning

One version, one file

The VERSION file at the repository root holds the current release — 0.1.0 — as plain semver (no leading v). Everything reads it:

Where Shows
make build stamps it into the binary: ims version → ims 0.1.0
go run, air, tests the same number with a suffix: ims 0.1.0-dev — a local build is never mistaken for a release
/api/v1/system/info, /api/health, the dashboard the running version
this site the badge next to the title

internal/version/version_test.go fails if VERSION isn’t valid semver.

What the numbers mean

While the version starts with 0., the API is young: a minor bump (0.1.0 → 0.2.0) may contain breaking changes, a patch bump (0.1.0 → 0.1.1) never does. From 1.0.0 on, the usual rules apply:

Bump When
major breaking changes to the HTTP API, config or CLI
minor new features, new endpoints, new settings — backwards compatible
patch fixes only

Cutting a release

  1. Make sure main is green (CI runs format, lint, tests, generated-code and contract checks).

  2. Update VERSION and move the “Unreleased” notes in CHANGELOG.md under the new number with today’s date.

  3. Regenerate anything version-dependent and commit:

    Terminal window
    make docs-gen gen-check
    git commit -am "release: v0.2.0"
  4. Tag and push:

    Terminal window
    git tag -a v0.2.0 -m "v0.2.0"
    git push origin main --tags
  5. On GitHub, draft a release for the tag with the changelog section as notes, and publish it.

  6. Deploy the binary with the deploy runbook (release.sh builds with the tag’s version and runs migrations as a gated step).

Publishing the documentation

The docs site is a fully static Astro Starlight build in website/; its pages are this repository’s docs/ folder. Cloudflare only serves the built files — nothing of the Go application runs there.

Automatically: publishing a GitHub Release runs .github/workflows/docs-deploy.yml, which builds the site and uploads it to Cloudflare Workers (static assets). You can also run the workflow by hand from the Actions tab, e.g. after a docs-only fix.

One-time setup:

  1. In Cloudflare: My Profile → API Tokens → Create Token, template Edit Cloudflare Workers.
  2. In GitHub: Settings → Secrets and variables → Actions, add CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (shown on your Cloudflare Workers overview page).
  3. Optionally add a repository variable DOCS_SITE_URL with the final address (for canonical links and the sitemap).

The first deploy creates the ims-go-api-starter worker; the site is then live at https://ims-go-api-starter.<your-subdomain>.workers.dev. A custom domain can be added later in the Cloudflare dashboard without changing anything here.

By hand, from your machine:

Terminal window
cd website
npm ci
npx wrangler login # once
npm run deploy # builds, checks every link, uploads dist/

Writing docs locally

Terminal window
make docs # live preview at http://localhost:4321 (Node 22.23+)
make docs-build # production build + link check
make docs-gen # regenerate the reference pages (CLI, config, permissions, make)