keysat/CUTTING_V0.2.0.md

Cutting v0.2.0:0

The v0.2.0 milestone version is drafted at startos/versions/v0.2.0.ts but not yet wired in as the current version. This file documents exactly what to do when you're ready to flip the switch.

Pre-flight (do these once, before the cut)

1. Read through startos/versions/v0.2.0.ts — especially the release notes. The notes ship to every operator who installs or upgrades; treat them as the public-facing changelog. Edit freely.
2. Sanity-check the SPA at /admin/ on a running :46 daemon. The v0.2 cut is the one where the SPA is "officially" the primary interface; if anything's still rough, fix it on the alpha line first.
3. Confirm no schema changes are pending. v0.2.0:0 is a label change, not a data migration — licensing-service/migrations/ should still end at 0009. (When v0.3 ships its first schema change, that's a 0010_*.sql file and the migration regression tests in tests/migrations.rs will run against it automatically.)

The cut itself (≈5 minutes)

Step 1 — Wire v0.2.0 in as the current version

Edit startos/versions/index.ts:

import { v0_1_0 } from './v0.1.0'
import { v0_2_0 } from './v0.2.0'   // ← add

export const versions = VersionGraph.of({
  current: v0_2_0,                  // ← change from v0_1_0
  other: [v0_1_0],                  // ← add so 0.1.0:N can upgrade
})

Step 2 — Type-check + build

cd licensing-service-startos
npm run check         # tsc --noEmit; should pass
make x86              # produces keysat_x86_64.s9pk for v0.2.0:0

If the SDK's VersionInfo.of signature wants a migration callback for the upgrade from v0.1.0 → v0.2.0, the tsc step will tell you. The current draft has no migration callback because there's no on- disk transformation needed — but if start-sdk enforces one, add an empty one:

export const v0_2_0 = VersionInfo.of({
  version: '0.2.0:0',
  releaseNotes: [...],
  migrations: {
    up: async () => { /* no-op */ },
    down: async () => { /* no-op */ },
  },
})

Step 3 — Publish

~/.keysat/publish.sh

The publish script's gate (current version differs from ~/.keysat/last_published_version) will fire because 0.2.0:0 is a new version string. The script handles upload + registry-add as usual.

Step 4 — Verify the upgrade dialog

Refresh the StartOS marketplace on a test instance running v0.1.0:46 (or any v0.1.0:N). It should now show v0.2.0:0 as available with the release notes from v0.2.0.ts rendered. Click "Update" and confirm the daemon comes up cleanly post-upgrade.

If the test instance gets stuck (StartOS won't compute the upgrade graph, daemon panics post-upgrade, anything weird): the v0.2.0:0 .s9pk is still in the registry but you can pull it via start-cli registry package remove keysat 0.2.0:0 and roll back to the alpha line by reverting versions/index.ts.

Rollback

If it goes sideways:

# Revert versions/index.ts to use v0_1_0 as current
git checkout HEAD~1 -- startos/versions/index.ts

# Bump to a fresh alpha-iteration revision (so the registry has
# something newer than the busted 0.2.0:0)
# Edit startos/versions/v0.1.0.ts → version: '0.1.0:47'
# with release notes explaining the rollback.

# Build + publish
make x86
~/.keysat/publish.sh

The bad v0.2.0:0 stays in the registry but operators on v0.1.0:46 won't see it as the latest if a newer v0.1.0:47 is present (StartOS picks the highest-version compatible release).

Why v0.2.0:0 (not v0.2)

The version string is ExVer (<upstream>:<downstream>). 0.2.0 is the upstream milestone; :0 is the wrapper revision. The next routine wrapper change on the v0.2 line is 0.2.0:1. v0.2's first schema change is a new SQL migration file — the upstream version doesn't move for that.

The upstream version 0.3.0 opens when we ship a substantial feature set (Zaprite, recurring subscriptions, tier upgrades, etc.) that warrants the marketing distinction.