Releasing

The Desktop installers workflow builds four editions across Mac Apple silicon/Intel, Windows x64, and Linux x64. Mac downloads contain native .saver bundles; Windows and Linux downloads contain desktop apps. Releases include SHA256SUMS and release-manifest.json.

Preview releasesCopy Anchor Link

Relevant changes on main automatically produce unsigned preview prereleases. Pull requests build representative platform/architecture candidates without publishing.

Start a full preview manually, replacing BRANCH with the intended branch:

gh workflow run desktop.yml --ref BRANCH -f publish=true

Use -f publish=false for a build-only run. Preview builds remain labeled unsigned in the manifest, release notes, and website.

Stable releasesCopy Anchor Link

Stable publication uses a version tag matching package.json, such as v0.2.0, on a commit already integrated into main. The complete expected matrix and Mac/Windows signing verification must pass before publication.

Credentials belong in the release environment, and pull-request builds do not need them. See signing setup for required credentials and verification commands.

On Mac, verify the .saver bundle installs, appears in the system settings, loads in the native preview, and follows macOS activation/dismissal behavior. On Windows/Linux, verify app installation, launch, tray, idle activation, and uninstall. A successful packaging job alone does not establish these behaviors.

Download metadataCopy Anchor Link

The manifest records each artifact's asset, OS, architecture, version, public URL, filename, byte size, checksum, signing status, and kind (screensaver or application). Legacy schema-1 entries without kind are applications, including archived Mac downloads; they must retain that label. Names follow:

bloxwap-screensaver-{asset-slug}-{version}-{os}-{arch}.{format}

The complete matrix remains 16 build targets and 28 files: DMG and ZIP containing the native .saver for two Mac architectures, one Windows installer, and AppImage and DEB for Linux, for each of four assets.

Publication refreshes GitHub Pages with verified metadata. The site prefers a valid stable release; preview publication preserves that stable homepage when one exists. Links point to a specific public GitHub Release without sign-in. Failed or incomplete builds do not replace the current download list.

For a local site build, fetch the latest valid stable release, or the latest preview when no stable release exists:

node scripts/fetch-release.mjs
npm run docs:build

Use --tag TAG to select a release. See the release runbook for reruns, rollback, and evidence to record before closing release tasks.