Document the release and push flow for future sessions
All checks were successful
Validate Kaleido Desktop / validate (push) Successful in 1m21s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-10-30 17:28:04 -07:00
parent 4478d2206d
commit be865fa992
4 changed files with 55 additions and 16 deletions

View file

@ -24,4 +24,14 @@
- Mute before playback tests (`__kaleido.useSettings.getState().set('volume', 0)`). - Mute before playback tests (`__kaleido.useSettings.getState().set('volume', 0)`).
Playback changes real Plex progress and track selections; restore them. Playback changes real Plex progress and track selections; restore them.
## Releases
Built and published locally (CI only validates). In short: bump the version in
`package.json`, `src-tauri/Cargo.toml`, `src-tauri/tauri.conf.json` (+ lockfile), add a
`CHANGELOG.md` section, `.\scripts\build.ps1`, commit + tag `vX.Y.Z` + push,
`node scripts/publish-release.mjs X.Y.Z [--prerelease]`, then
`node scripts/update-manifest.mjs X.Y.Z <release download URL>` and commit/push
`updates/latest.json`. Full checklist: `docs/development.md` → Releases. Only push or
publish when the user asks. `FORGEJO_TOKEN` lives in the ignored `.env`.
See `docs/architecture.md` and `docs/development.md`. See `docs/architecture.md` and `docs/development.md`.

1
CLAUDE.md Normal file
View file

@ -0,0 +1 @@
@AGENTS.md

View file

@ -33,21 +33,43 @@ for that file.
## Releases ## Releases
1. Bump the version in `package.json`, `src-tauri/Cargo.toml` and Releases are built and published from this Windows machine. CI only validates; it never
`src-tauri/tauri.conf.json`. builds installers on push (there are no Windows/macOS runners). Versions follow SemVer;
2. `.\scripts\build.ps1` builds the NSIS installer and its signed updater artifact. The betas use a prerelease suffix (`0.1.0-beta.1`) and are published as pre-releases.
updater key is read from `.tools/updater.key` (ignored; keep it safe — replacing it
breaks in-app updates for existing installs) or from `TAURI_SIGNING_PRIVATE_KEY`. Checklist for version `X.Y.Z` (run from the repository root):
3. Commit, tag `vX.Y.Z` and push, then
`node scripts/publish-release.mjs X.Y.Z [--prerelease]` creates the Forgejo release 1. **Version**: set `X.Y.Z` in `package.json`, `src-tauri/Cargo.toml` and
with the installer and its `.sig` (notes come from `CHANGELOG.md`). It reads `src-tauri/tauri.conf.json`, then `npm install --package-lock-only` to update
`FORGEJO_TOKEN` (repository read/write) from the environment or the ignored `.env`. `package-lock.json`.
4. `node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z notes.md` 2. **Changelog**: add a `## X.Y.Z` section at the top of `CHANGELOG.md`. It becomes the
and commit `updates/latest.json`. Installed copies offer the update on their next release notes and the in-app update notes.
start. 3. **Check**: `npm run typecheck`, `npm test`, `cargo check --manifest-path src-tauri/Cargo.toml`.
4. **Build**: `.\scripts\build.ps1` → `src-tauri/target/release/bundle/nsis/Kaleido_X.Y.Z_x64-setup.exe`
and its `.sig`. The updater key is read from `.tools/updater.key` (ignored; keep it
safe — replacing it breaks in-app updates for existing installs) or from
`TAURI_SIGNING_PRIVATE_KEY`.
5. **Commit and tag**: commit as `Release Kaleido Desktop X.Y.Z`, then
`git tag -a vX.Y.Z -m "Kaleido Desktop X.Y.Z"` and `git push origin main vX.Y.Z`
(SSH remote `origin`, already configured).
6. **Publish**: `node scripts/publish-release.mjs X.Y.Z` (add `--prerelease` for betas)
creates the Forgejo release with the notes from `CHANGELOG.md` and uploads the
installer and `.sig`. It reads `FORGEJO_TOKEN` (repository read/write) from the
environment or the ignored `.env`, and never prints it. Re-running it replaces the
assets.
7. **Update feed**: `node scripts/update-manifest.mjs X.Y.Z https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/releases/download/vX.Y.Z`
rewrites `updates/latest.json`; commit it (`Publish the X.Y.Z update feed`) and push.
Installed copies offer the update on their next start. Publish the feed only after
the release assets exist, or clients would be sent to a missing file.
8. **Verify**: download the installer from the release URL and compare its SHA-256 with
the local file; `https://git.elijahkuntz.com/Elijah/Kaleido-Desktop/raw/branch/main/updates/latest.json`
should show the new version; CI on Actions should finish green.
The installer is per user (`%LOCALAPPDATA%\Kaleido`, no admin) and is not code-signed,
so SmartScreen warns on first run. In-app updates run it in passive mode and relaunch.
For macOS and Linux, build on those systems (`scripts/fetch-libmpv.sh`, then For macOS and Linux, build on those systems (`scripts/fetch-libmpv.sh`, then
`npx tauri build`) and merge their bundles into the same feed with `KALEIDO_BUNDLES`. `npx tauri build`) and merge their bundles into the same feed with `KALEIDO_BUNDLES`.
CI (`.forgejo/workflows/release.yml`) validates every push and tag. Installers are `.forgejo/workflows/release.yml` validates every push and tag;
built locally; `.forgejo/workflows/build-installers.yml` can build them in CI once `.forgejo/workflows/build-installers.yml` can build installers in CI once runners exist
runners exist for each platform, and only runs when started by hand. for each platform, and only runs when started by hand.

View file

@ -1,5 +1,6 @@
// Writes updates/latest.json, the feed Kaleido's updater reads, from built bundles. // Writes updates/latest.json, the feed Kaleido's updater reads, from built bundles.
// Usage: node scripts/update-manifest.mjs <version> <baseDownloadUrl> [notesFile] // Usage: node scripts/update-manifest.mjs <version> <baseDownloadUrl> [notesFile]
// Notes come from the version's CHANGELOG.md section unless a notes file is given.
// Each platform's signed artifact (and its .sig) must be in src-tauri/target/release/bundle, // Each platform's signed artifact (and its .sig) must be in src-tauri/target/release/bundle,
// or pass several bundle folders via KALEIDO_BUNDLES (path;path) when collecting CI outputs. // or pass several bundle folders via KALEIDO_BUNDLES (path;path) when collecting CI outputs.
import fs from 'node:fs'; import fs from 'node:fs';
@ -24,7 +25,12 @@ const PLATFORMS = [
const manifestPath = path.join(root, 'updates/latest.json'); const manifestPath = path.join(root, 'updates/latest.json');
const manifest = fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : { platforms: {} }; const manifest = fs.existsSync(manifestPath) ? JSON.parse(fs.readFileSync(manifestPath, 'utf8')) : { platforms: {} };
manifest.version = version; manifest.version = version;
manifest.notes = notesFile ? fs.readFileSync(notesFile, 'utf8').trim() : manifest.notes ?? ''; // Notes default to this version's section of CHANGELOG.md.
const changelogNotes = () => {
const section = fs.readFileSync(path.join(root, 'CHANGELOG.md'), 'utf8').split(/^## /m).find((x) => x.startsWith(version));
return section ? section.slice(version.length).trim() : '';
};
manifest.notes = notesFile ? fs.readFileSync(notesFile, 'utf8').trim() : changelogNotes();
manifest.pub_date = new Date().toISOString(); manifest.pub_date = new Date().toISOString();
manifest.platforms ??= {}; manifest.platforms ??= {};