openswarm/docs/RELEASE_CHECKLIST.md

# Release Checklist

Copy this into the release PR/issue and tick every box before promoting a draft
release to `latest`. The goal: no broken build ever reaches users on either
platform. See `RELEASE_RUNBOOK.md` for the how; this is the gate.

## Pre-build
- [ ] `dev` is green and dogfooded; the release commit is chosen.
- [ ] `electron/package.json` `version` bumped per semver (CONTRIBUTING.md).
- [ ] `backend/requirements.lock` regenerated if `requirements.txt` changed, and
      committed alongside it.
- [ ] Both `package-lock.json` files committed (frontend + electron).

## Build (both platforms, same commit)
- [ ] macOS DMG built from the release commit (`bash publish.sh`), signed +
      notarized, both arches (arm64 + x64).
- [ ] Windows EXE built from the same commit (push `v*` tag → CI, or
      `pwsh publish-win.ps1`), signed.
- [ ] Provenance matches: launch each artifact, Settings → About → **Build** sha
      equals `git rev-parse HEAD` of the release commit (and they equal each other).

## Bundle size (cheap, and it has already caught a 175MB regression)
- [ ] `du -sh electron/dist/*/OpenSwarm.app/Contents/Resources/app.asar` is **~2.5MB**.
      Anything above ~10MB means a build artifact got swept in. See "The asar trap" below.
- [ ] Each DMG is within ~10% of the previous release's size (1.7.9: ~300MB).
- [ ] `git status electron/package.json` is clean. electron-builder **rewrites it in place**
      during packaging, leaving a 10-line stub with no `build` section; restore it with
      `git checkout HEAD -- electron/package.json` before any second build.

### The asar trap

**`.gitignore` and `build.files` are two separate exclusion lists, and nothing checks them
against each other.** A file can be invisible to git and still be packed into the app.

Caught 2026-08-24: `electron/whisper/ggml-small.en-q5_1.bin` is a **181MB dictation model
downloaded at runtime into userData** (`electron/voice/whisperModels.js` resolves it from
`userDataDir`; nothing reads it from the bundle). It is gitignored, but `build.files` did not
exclude it, so electron-builder swept it into `app.asar`:

| | app.asar | DMG |
| --- | --- | --- |
| v1.7.9 (published) | 2.5MB | 300MB |
| exp.1 first build | **184MB** | **475MB** |
| exp.1 after the fix | 2.5MB | 309MB |

That is **175MB on every auto-update**, for a file the app never reads.

**Why it stayed hidden:** v1.7.9 was cut in a **detached worktree**, which by definition
contains no gitignored files. So the bug is invisible on a clean cut and fires on any
developer machine that has ever used dictation. A green build on one machine proves nothing
about the next.

Fixed by adding `!whisper` / `!whisper/**` to `build.files`, pinned by
`electron/packaging.test.js`. When adding anything to `.gitignore` that lives under
`electron/`, ask whether `build.files` needs the same entry.

## Artifacts + feeds (promotion gate)
- [ ] GitHub draft release for `v<version>` has: `OpenSwarm-Setup-x64.exe`,
      `OpenSwarm-arm64.dmg`, `OpenSwarm-x64.dmg`, `latest.yml`, `latest-mac.yml`.
- [ ] Promotion gate passes:
      `node scripts/release/verify-release.js --dir <downloaded-feeds> --expect-version <version> --base-url https://github.com/openswarm-ai/openswarm/releases/download/v<version>`
      (both feeds present, versions agree with each other and with package.json,
      every asset HEAD-resolves to 200).

## Dogfood on real target OSes (in production, signed)
- [ ] Windows 11 x64: fresh install of the signed EXE, no SmartScreen block after
      signing, app boots, backend reaches ready, send one agent message (gets a
      response). Check `backend.log` `[provenance]` + `[perf]` lines.
- [ ] Windows 10 x64: same.
- [ ] macOS Apple Silicon (arm64), macOS 12+: fresh DMG install, no Gatekeeper
      block, boots, backend ready, one agent turn.
- [ ] macOS Intel (x64), macOS 12+: same.
- [ ] Auto-update: previous stable installed → this release detected, downloads,
      installs on quit, relaunches on the new version. Verify on both platforms.
- [ ] Widevine DRM: in a Browser card open a Spotify playlist (or any DRM title)
      and confirm a track plays PAST the ~10s encrypted boundary and auto-advances,
      with no `[drm-diag] License response 500` in the logs. A signed-but-not-VMP
      build boots fine and only fails here, so this box catches it. Both platforms.

## Promote
- [ ] All boxes above ticked.
- [ ] Remove the draft flag (publish the release) — this is the only manual
      promote step; nothing auto-promotes.
- [ ] Confirm `latest.yml` / `latest-mac.yml` are live (HEAD 200) post-publish.

## Rollback (if a regression surfaces post-promote)
- [ ] Re-publish the previous release's feeds as latest, or cut a patch.
- [ ] Tags are immutable (ruleset) — never move `v<version>`; ship a new version.