# Release process (manual, local signing, per platform)

All TUF signing keys stay on your machine, one keystore per platform, in
`./<platform>/keystore` (gitignored — never commit it). Nothing here touches
CI or GitHub Secrets — Linux/macOS builds and signing should also happen
locally (a Linux build machine, or WSL2 on Windows works fine — PyInstaller
doesn't cross-compile, so you must actually run the build on the target OS).

`<platform>` is `win`, `mac`, or `linux` — whichever `python` is currently
running on (`core.updater._platform_key()` / the matching helper in
`repo_init.py`/`repo_release.py` decide this automatically; you never pass
it explicitly). Each platform gets a fully independent tree:
```
scripts/release/
  win/{keystore,repository}/
  linux/{keystore,repository}/
  mac/{keystore,repository}/
```
Why fully separate rather than shared: a Windows build and a Linux build of
the same app version are different byte-for-byte archives, and TUF's
metadata filenames (`root.json`, `timestamp.json`, ...) aren't
platform-prefixed — sharing one repo/release between platforms means one
platform's publish silently overwrites the other's trust root and metadata.

## One-time setup (repeat once per platform, on that platform)

```
pip install -r requirements-dev.txt
python scripts/release/repo_init.py
```

Generates `scripts/release/<platform>/keystore/` (private + public keys for
the root/targets/snapshot/timestamp TUF roles) and
`scripts/release/<platform>/repository/` (initial signed metadata, including
`root.json`).

**Back up `<platform>/keystore/` immediately, somewhere private and durable
outside this repo — one backup per platform.** Losing a platform's root key
means you can never publish a trusted update to that platform's existing
installs again — they'd all need a fresh, non-updating reinstall. Losing one
platform's key doesn't affect the others (that's the point of keeping them
separate).

Rebuild once more (`pyinstaller labui.spec`) after this step, so the
freshly-generated `root.json` gets bundled into the app (see the `.spec`
file's `_root_json` check — it only bundles the file if it already exists,
and it reads from *this platform's* tree).

## Every release (repeat once per platform, on that platform)

1. Bump `__version__` in `core/version.py` (same version number across all
   platforms for a given release, even though each is signed/published
   separately).
2. `pyinstaller labui.spec` → produces `dist/LabUI/` for *this* OS.
3. `python scripts/release/repo_release.py` → creates+signs
   `scripts/release/<platform>/repository/targets/labui-<version>.tar.gz`
   and updates the metadata files in
   `scripts/release/<platform>/repository/metadata/`.
4. Create (first time) or reuse the GitHub Release tagged
   **`updates-<platform>`** (e.g. `updates-win`, `updates-linux`) on this
   repo, and upload every file from
   `scripts/release/<platform>/repository/metadata/` and
   `scripts/release/<platform>/repository/targets/` as release assets,
   **replacing** any same-named files already there.
   - Each platform's tag is fixed on purpose — the app's
     `metadata_base_url` (computed by `core.updater._platform_key()`)
     always points at
     `https://github.com/<owner>/<repo>/releases/download/updates-<platform>/`.
     A normal per-version-tagged release would give every version a
     different URL, which breaks TUF's requirement that top-level metadata
     live at a stable location — and a *shared* tag across platforms would
     break the platform-isolation described above.
   - Cut a normal, separately-tagged human-facing release too if you want a
     changelog/download page (e.g. `v1.2.3`, one release with per-platform
     zip assets attached) — this doesn't have to be the same release as the
     `updates-*` ones, and normally shouldn't be (see `docs/building.md`).
5. Test: launch a previous installed version of *this platform*,
   Settings → Check for Updates, confirm it finds and applies the new
   version.

## Re-signing without a new release

Metadata expires even if nothing changed (`expiration_days` in
`repo_init.py`: root 365 days, targets/snapshot/timestamp 90 days) —
per platform, independently. If you haven't shipped a release for a given
platform before its targets/snapshot/timestamp expire, that platform's
clients will start rejecting the metadata as stale. Re-sign:

```
python -m tufup sign snapshot scripts/release/<platform>/keystore
python -m tufup sign timestamp scripts/release/<platform>/keystore
```

(run from the repo root; substitute the actual platform directory) and
re-upload the resulting files to that platform's `updates-<platform>`
release. Set a calendar reminder per platform — there is no automation for
this on purpose (manual signing was a deliberate choice, not an oversight).