Versioning

Versioning

Strata uses git describe --tags --dirty --always as the runtime source of truth for the version string displayed in the app. On every release, all six version-carrying files are kept in sync by npm run release -- X.Y.Z.

Files updated on every release

File	How updated
package.json (root)	scripts/release.mjs — bumped to X.Y.Z
backend/package.json	scripts/release.mjs — bumped to X.Y.Z
front/package.json	scripts/release.mjs — bumped to X.Y.Z
docs/package.json	scripts/release.mjs — bumped to X.Y.Z
src-tauri/Cargo.toml	scripts/release.mjs — bumped to X.Y.Z
src-tauri/tauri.conf.json	scripts/release.mjs — bumped to X.Y.Z

The runtime version displayed in the UI is still derived from git describe — so on a clean tag commit those always agree.

The 3 scripts (Single Responsibility Principle)

scripts/version.mjs       ← READS: shells out to git describe
scripts/gen-version.mjs   ← WRITES: produces version.json and version.ts from version.mjs
scripts/release.mjs       ← RELEASES: bumps 6 files, commits, tags, pushes

scripts/version.mjs

Single export versionInfo(). Shells out to git describe --tags --dirty --always. Falls back gracefully when no tags exist or git is unavailable.

Git state	Example	env label
Clean checkout on a tag	1.4.2	production
Tag + commits since	1.4.2-3-gabcd123	development
Tag + uncommitted changes	1.4.2-3-gabcd123-dirty	development
No tags at all	0.0.0-dev+abcd123-dirty	development

Anything that is not a clean tag is flagged as development.

STRATA_ENV override

Set STRATA_ENV=development or STRATA_ENV=production to force the env field regardless of what git describe returns. Used by docker:reset and docker:nuke to ensure the docs Docker image is always labelled DEV even when building from a clean release tag:

STRATA_ENV=development node scripts/gen-version.mjs all

docker:prod does not use this — it uses VERSION_OVERRIDE=$(git describe --tags --abbrev=0) which yields a clean semver, so env=production is derived naturally.

package.json version fallback

When git describe returns 0.0.0-dev (shallow clone with no reachable tags — e.g. Cloudflare Pages CI), version.mjs reads the version from the root package.json instead. Since release.mjs always bumps package.json in sync with git tags, this always yields the correct release version (e.g. 1.0.0). A clean semver → isClean=true → env=production is derived automatically — no extra environment variable needed for the deployed docs site.

scripts/gen-version.mjs

Writes generated files that embed the current version into each package at build time:

node scripts/gen-version.mjs backend  → backend/src/_generated/version.json
node scripts/gen-version.mjs front    → front/src/lib/version.ts
node scripts/gen-version.mjs docs     → docs/src/lib/version.ts
node scripts/gen-version.mjs all      → all three at once

These files are gitignored. They are regenerated by prebuild/pretest scripts and by npm run docker:reset / npm run docker:prod.

scripts/release.mjs

The release workflow. Run: npm run release -- X.Y.Z

Steps executed:

1. Validate semver format (X.Y.Z)
2. Check working tree is clean
3. Bump version in all 6 files listed above
4. git commit -m "chore: release vX.Y.Z"
5. git push origin HEAD
6. git tag vX.Y.Z
7. git push origin vX.Y.Z
8. gh release create vX.Y.Z --generate-notes --title "vX.Y.Z" — creates the GitHub Release with auto-generated changelog (requires gh CLI, authenticated)

Use --dry-run to preview all steps without executing git/gh commands:

npm run release -- 1.2.3 --dry-run

Use --no-push to bump, commit and tag locally without pushing to the remote:

npm run release -- 1.2.3 --no-push
# Then push manually when ready:
#   git push origin HEAD
#   git push origin v1.2.3
#   gh release create v1.2.3 --generate-notes --title "v1.2.3"

Use --no-gh-release to push the git tag without creating a GitHub Release (e.g. in CI without gh auth):

npm run release -- 1.2.3 --no-gh-release

Release notes are auto-generated from conventional commit messages since the previous tag, grouped by type (features, bug fixes, docs, other). The chore: release commit itself is excluded.

How to release

# 1. Ensure tests pass
npm test --prefix backend && npm run test:e2e --prefix backend
npm test --prefix front

# 2. Tag and push (bumps 6 version files, commits, tags, creates GitHub Release)
npm run release -- 1.4.2

# 3. Write the release notes doc
#    Create docs/src/content/docs/releases/v1-4-2.md
#    Update docs/src/content/docs/releases/index.md (add row to table)
#    Commit and push

# 4. Build the production stack
npm run docker:prod        # Docker
npm run tauri:prod         # Desktop app (macOS)

Release notes doc

Every release needs a corresponding Markdown page in docs/src/content/docs/releases/:

File	Content
vX-Y-Z.md	Human-readable release notes — what changed and why
index.md	Index table — add a row for the new version

Frontmatter template (docs/src/content/docs/releases/vX-Y-Z.md):

---
title: "Release Notes — vX.Y.Z"
description: "One sentence summary of what's in this release."
sidebar:
  order: N   # 1 = newest, increment for each older release
---

After adding the doc, commit and push so the live docs site updates:

git add docs/src/content/docs/releases/
git commit -m "docs(releases): add v1.4.2 release notes"
git push

Where the version is shown

Surface	Location	DEV example	PROD example
Backend HTTP	GET /api/v1/version	{"version":"1.4.2-3-gabcd","env":"development",…}	{"version":"1.4.2","env":"production",…}
Backend health	GET /api/v1/health	included in payload	included in payload
Docs sidebar	site title badge	v1.4.2-3-gabcd — DEV (orange)	v1.4.2 (no badge)
Frontend sidebar	bottom-left footer	v1.4.2-3-gabcd-dirty DEV	v1.4.2
Frontend Settings	About panel	full version + git SHA + build time	full version + git SHA + build time
Desktop window title	always visible	Strata 0.0.0-dev+abcd-dirty (DEV)	Strata 1.4.2
Desktop About menu	menu bar → Strata → About	full version + env + data folder	full version + env + data folder

AI agent versioning skill

When working with an AI agent (GitHub Copilot, Claude, etc.), say “create version” or “release X.Y.Z” to invoke the sem-ver skill. The skill will:

1. Ask Socratic questions to determine the correct bump (MAJOR / MINOR / PATCH)
2. Suggest the next version number
3. Ask you to confirm or override
4. Run the release checklist and execute npm run release -- X.Y.Z

Semver rules for Strata

Bump	When to use
PATCH (X.Y.Z+1)	Bug fix, UI polish, perf tweak, docs — no DB schema change, no new API endpoints
MINOR (X.Y+1.0)	New feature, new API endpoint, new UI page — backward-compatible DB migration
MAJOR (X+1.0.0)	Breaking API change, destructive DB migration, Tauri major version bump