Releasing K3 Studio

A release is a git tag. Pushing a v* tag runs the release workflow. The workflow builds K3 Studio with that version, packs the installer and publishes it as a GitHub release. Installed copies of K3 Studio see the new release the next time they start and update themselves (see Updates).

How to release

1. Get master ready. Merge everything that ships and make sure the working tree is clean.

2. Run the full test suite and make sure it passes:

   ./run.sh test
   

3. Do a release build and try it by hand: open a workspace, start the server, edit and save a file.

   K3_VERSION=0.1.0 ./run.sh release
   

4. Write the release overview in docs/releases/vX.Y.Z.md (named after the tag) and commit it. It opens the release notes on GitHub, above the generated commit list. Keep it brief: a few bullets on what users get, grouped (new, improved, fixes), plus anything they must do after updating (a renamed setting, tools to allow again). Leave out website, test and docs changes. The workflow refuses to release a tag without this file. See v0.2.5 for an example.

5. Push master:

   git push origin master
   

6. Tag the commit you tested and push the tag:

   git tag v0.1.0
   

   git push origin v0.1.0
   

7. Watch the run in the repository's Actions tab. When it's green, the release is at https://github.com/Kr3mu/k3studio/releases with K3Studio-0.1.0-setup.exe attached, your overview first and the generated commit list under it.

8. Edit the release notes on GitHub if needed, for example to call out breaking changes or new settings.

9. Check the update: start an older installed K3 Studio. With auto-update on, it downloads the new version and installs it when you quit. With auto-update off, it asks.

Rules

Versions

• Tags are vMAJOR.MINOR.PATCH, for example v0.4.2. The updater compares the numbers part by part, so v1.10.0 is newer than v1.9.3.
• No pre-release tags (v1.0.0-rc1, v1.0.0-beta). The updater can't compare them.
• Keep the steps small: bump PATCH or a small MINOR step (0.2.0 → 0.2.5 → 0.3.0), not big jumps.
• Every release has a higher version than the one before. The updater only installs a version newer than the one that's running.
• Bump PATCH for fixes only, MINOR for new features or settings, and MAJOR for changes that break existing workspaces, settings files or fed-bridge. Before 1.0, MINOR covers breaking changes too.
• The version only comes from the tag. Don't put it in code: release builds get it as -define:K3_VERSION=..., and builds from source report dev and never update.

Tags and releases

• Only tag commits on master that passed ./run.sh test.

• Never move, delete or re-push a tag once its release is published. Installed copies may already have downloaded that installer.

• If the workflow fails before publishing, delete the tag, fix the problem, and tag again with the same version:

  git push origin :refs/tags/v0.1.0
  

  git tag -d v0.1.0
  

• If a published release is broken, don't delete it. Fix it forward with a new PATCH release. To roll back, release the old code under a new, higher version.

• A release must not be a draft or marked pre-release. The updater reads GitHub's latest release and skips both.

The installer

• The installer asset must keep the -setup.exe suffix (K3Studio-<version>-setup.exe). That suffix is how the updater finds it.
• Never change the AppId in installer/k3studio.iss. If it changes, Windows treats the new install as a separate program and the old one stays behind.
• The installer stays per-user (PrivilegesRequired=lowest). Silent updates rely on not needing admin.
• A new file that K3 Studio needs at runtime (a DLL or data file not baked in with #load) must be added to [Files] in the installer script, or installed copies break.
• The installer must keep working with /VERYSILENT (install on quit) and /SILENT /RELAUNCH (update and restart). Don't add wizard pages that need input in silent mode.

The repository

• The repository must be public. The updater and installer downloads use GitHub without signing in, and a private repository answers them with 404.
• The updater checks Kr3mu/k3studio (RELEASES_API in src/updates.odin). If the repository is renamed or moved, update that constant and ship a release from the old location first, so existing installs find the new one.
• The workflow needs no secrets: it publishes with the built-in GITHUB_TOKEN. It runs with contents: write permission.