# Releasing K3 Studio

A release is a git tag. Pushing a `v*` tag runs [the release workflow](../.github/workflows/release.yml). The workflow builds K3 Studio with that version, packs [the installer](../installer/k3studio.iss) 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](getting-started.md#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:

   ```bash
   ./run.sh test
   ```

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

   ```bash
   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](releases/v0.2.5.md) for an example.

5. Push `master`:

   ```bash
   git push origin master
   ```

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

   ```bash
   git tag v0.1.0
   ```

   ```bash
   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:

  ```bash
  git push origin :refs/tags/v0.1.0
  ```

  ```bash
  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.