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
-
Make sure
mainis green (CI runs format, lint, tests, generated-code and contract checks). -
Update
VERSIONand move the “Unreleased” notes inCHANGELOG.mdunder the new number with today’s date. -
Regenerate anything version-dependent and commit:
Terminal window make docs-gen gen-checkgit commit -am "release: v0.2.0" -
Tag and push:
Terminal window git tag -a v0.2.0 -m "v0.2.0"git push origin main --tags -
On GitHub, draft a release for the tag with the changelog section as notes, and publish it.
-
Deploy the binary with the deploy runbook (
release.shbuilds 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:
- In Cloudflare: My Profile → API Tokens → Create Token, template Edit Cloudflare Workers.
- In GitHub: Settings → Secrets and variables → Actions, add
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_ID(shown on your Cloudflare Workers overview page). - Optionally add a repository variable
DOCS_SITE_URLwith 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:
cd websitenpm cinpx wrangler login # oncenpm run deploy # builds, checks every link, uploads dist/Writing docs locally
make docs # live preview at http://localhost:4321 (Node 22.23+)make docs-build # production build + link checkmake docs-gen # regenerate the reference pages (CLI, config, permissions, make)