mirror of
https://github.com/openswarm-ai/openswarm.git
synced 2026-08-26 06:22:22 +02:00
92 lines
4.1 KiB
Markdown
92 lines
4.1 KiB
Markdown
# Release Runbook
|
|
|
|
How an OpenSwarm desktop release is built, verified, and promoted. The guiding
|
|
rule: **a release is reproducible and provenanced** — anyone can tell exactly
|
|
what commit produced a given DMG/EXE, and rebuilding that commit yields the same
|
|
bits. Distribution stays on GitHub Releases (auto-updater feeds live there).
|
|
|
|
## Versioning
|
|
|
|
Source of truth is `electron/package.json` `version`. Bump it only when cutting
|
|
a release (see CONTRIBUTING.md for semver rules). A `-` suffix (e.g.
|
|
`1.2.0-beta.1`) marks an experimental/pre-release build; the Windows CI and the
|
|
build scripts set the pre-release channel automatically from that suffix.
|
|
|
|
## What is pinned (reproducibility)
|
|
|
|
| Thing | Pin | Where |
|
|
|-------|-----|-------|
|
|
| uv | `0.11.16` | `scripts/build-app.sh`, `scripts/build-app-win.ps1` (override `UV_VERSION`) |
|
|
| Node (bundled runtime + CI toolchain) | `20.18.1` | build scripts, `.nvmrc`, `.github/workflows/*` |
|
|
| 9router | `0.3.60` | `scripts/fetch-router.{sh,ps1}` (override `ROUTER_VERSION`) |
|
|
| Python | `3.13.2` standalone | `scripts/build-python-env*.{sh,ps1}` |
|
|
| Python deps | fully hash-locked | `backend/requirements.lock` |
|
|
| npm deps | lockfile-exact via `npm ci` | `frontend/package-lock.json`, `electron/package-lock.json` |
|
|
| electron-builder + deps | exact (no `^`) | `electron/package.json` |
|
|
|
|
Both `package-lock.json` files are **committed** — `npm ci` refuses to run
|
|
without them. Do not re-add them to `.gitignore`.
|
|
|
|
### Regenerating the Python lock
|
|
|
|
After editing `backend/requirements.txt`:
|
|
|
|
```
|
|
uv pip compile backend/requirements.txt --python-version 3.13 \
|
|
--generate-hashes --output-file backend/requirements.lock
|
|
```
|
|
|
|
Commit both files together. Verify with a clean 3.13 env: install from the lock,
|
|
`uv pip check`, and import anthropic / pydantic / httpx / trafilatura /
|
|
claude_agent_sdk / uvicorn.
|
|
|
|
## Provenance
|
|
|
|
Every build writes `electron/build-info.json` (gitignored, regenerated) with the
|
|
`git rev-parse HEAD` sha, build time, channel, and version. It ships in the asar
|
|
and surfaces in two places:
|
|
|
|
- Startup log line in `backend.log`: `[provenance] OpenSwarm <ver> sha=<short> channel=<...>`
|
|
- Settings → General → Advanced → About → **Build**
|
|
|
|
To confirm an artifact's provenance: launch it, open Settings, and compare the
|
|
Build sha to `git rev-parse HEAD` of the tag you released.
|
|
|
|
## Build (local)
|
|
|
|
- macOS: `bash scripts/build-app.sh` (unsigned) / `--sign` / `--publish`.
|
|
Needs `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` for signing.
|
|
- Windows: `pwsh scripts/build-app-win.ps1` (unsigned) / `-Sign` / `-Publish`.
|
|
Signing is Azure Trusted Signing; CI handles it (see below).
|
|
|
|
## Release (CI)
|
|
|
|
Pushing a `v*` tag triggers `.github/workflows/release-windows.yml`, which builds
|
|
+ signs the Windows installer and uploads it to the GitHub Release for that tag.
|
|
macOS currently publishes from a Mac via `bash publish.sh`.
|
|
|
|
Recommended order so neither platform's users skip a version:
|
|
1. macOS: `bash publish.sh` (produces `latest-mac.yml`).
|
|
2. Windows: push the `v*` tag (or `pwsh publish-win.ps1`), producing `latest.yml`.
|
|
3. Verify both `latest.yml` and `latest-mac.yml` exist on the release and their
|
|
versions match before the release leaves draft.
|
|
|
|
## Tag protection (immutable releases)
|
|
|
|
Release tags must never move once cut — a moved tag silently re-points the
|
|
auto-updater feed at different bits. Configure a GitHub **ruleset** to enforce
|
|
this (Settings → Rules → Rulesets → New ruleset):
|
|
|
|
1. Target: **Tags**, pattern `v*`.
|
|
2. Enable **Restrict creations** off, **Restrict updates** on, **Restrict
|
|
deletions** on. (Equivalently: block non-fast-forward / force-push and
|
|
deletion on the `refs/tags/v*` ref.)
|
|
3. Apply to all users (no bypass list, or restrict bypass to break-glass only).
|
|
|
|
Verify: push a throwaway tag, then `git push --force origin <tag>` to move it →
|
|
GitHub must reject it. Delete the throwaway afterward (allowed only if you
|
|
temporarily exempt it, or use a non-`v*` name for the test).
|
|
|
|
GitHub releases are also independently markable immutable; tag protection is the
|
|
load-bearing control because the auto-updater resolves the tag, not the release.
|