Releasing Blanc

Releasing Blanc

Released versions are immutable — always bump to a new version, never overwrite assets. The pipeline is draft-first and fail-closed: nothing is tagged or published until every gate passes, and a failed attempt leaves no public artifacts.

The release flow, end to end

1. Release PR (squash-merged to main, titled "Release Blanc X.Y.Z") containing, in one commit:

   • the version bump in package.json + package-lock.json (consider the electron devDependency too — it tracks Chromium stable, and Chromium can't be swapped out of a running app);
   • the checked-in release notes docs/press/release-notes/vX.Y.Z.md (required; ordinary wrapped markdown — mirror the previous release's file);
   • the press-page version: const VERSION = 'X.Y.Z' in site/src/pages/press.astro and the literal version pin in test/unit/press-kit.test.js (assert.equal(packageVersion, 'X.Y.Z')). The verify gate fails the release if either lags the package version.

2. Run the script from a checkout whose HEAD is exactly origin/main (the script verifies this and refuses otherwise):

   BLANC_RELEASE_MODE=stable BLANC_RELEASE_PLATFORMS=mac,windows,linux BLANC_MAC_ARCHES=arm64,x64 npm run release

   All three env vars are required — the script exits immediately without them. BLANC_RELEASE_MODE=candidate requires a prerelease version (X.Y.Z-rc.N) and publishes with --prerelease; stable refuses prerelease versions. Every release ships both Mac architectures: Apple Silicon (arm64) is the default Mac build and the native host the script smoke-tests, and Intel (x64) ships alongside it so Intel installs keep updating. The script refuses a single architecture unless BLANC_MAC_ARCH_WAIVER gives the reason, which must also be recorded in the release incident. The post-release prerelease-smoke.yml dispatch verifies and launches the published Intel DMG on a native macos-15-intel runner.

3. After publication, the script regenerates site/src/data/releases.json from the GitHub release body (npm run site:changelog). Commit that as "Record Blanc X.Y.Z in the public changelog" (its own PR), then deploy the site (npm run site:deploy) — only from a checkout at origin/main: a production Pages deploy ships whatever the local tree contains, and a deploy from a stale checkout has silently rolled the live site back to older content before.

What the script does (and refuses)

scripts/release.sh authenticates via the gh CLI's cached session (no GH_TOKEN needed locally). In order: it refuses existing tags/releases for the version (immutability), refuses dirty release sources (a broad list: src, build, test, scripts, site, spec/substrate dirs, workflows, package.json/lock, the notes file), refuses a HEAD that isn't origin/main, then runs npm ci and the press verification gate (release:verify:press: substrate checks, unit tests, acceptance dry-run + desktop run, cold-launch smoke, OAuth desktop test, DNS smoke, npm audit --omit=dev --audit-level=high, site build). Only then does it build: notarized mac artifacts, a packaged first-run smoke test, and a migration test that downloads the public Stable base version and upgrades its profile. The immutable source tag is pushed first so CI runners can check out the exact commit, the draft release is created with the complete mac asset set (using gh release create directly — electron-builder's own GitHub publisher races per-artifact uploads and can leave a first publish missing latest-mac.yml or a blockmap), Windows/Linux builds are dispatched and watched, the full draft asset set is re-downloaded and verified against the expected manifest, SHA256SUMS is generated and uploaded, and only then is the draft published and every download URL smoke-checked logged-out.

First-attempt failure modes (all observed on v1.0.3)

• Press-kit pin: test/unit/press-kit.test.js hard-codes the version and requires press.astro's VERSION to match — bump both in the release PR itself (see step 1), not as an afterthought.
• npm audit: the security gate is fail-closed on high-severity advisories in production deps, including transitive ones (e.g. undici under electron's @electron/get). Fix is usually a lockfile-only npm audit fix --omit=dev, committed to main.
• Fresh worktree: root npm ci does not install the site's dependencies — run npm --prefix site ci too, or the site build dies with astro: command not found.
• Exit-code masking: don't pipe the release run through tee in a shell without pipefail — a failed release then reports exit 0 and reads as success.

Releasing from a throwaway git worktree works well when the primary checkout is dirty or shared with concurrent sessions: git worktree add <dir> origin/main, land the release PR, git checkout --detach origin/main in the worktree (detached HEAD passes the HEAD-equals-origin/main check), install both dependency trees, run the script, remove the worktree afterward.

macOS notarization

Notarization: the build step is wrapped in op run --env-file=.env.1password --no-masking -- ..., pulling APPLE_ID/APPLE_APP_SPECIFIC_PASSWORD from the 1Password item "Apple Notarization" (vault Dev, username/password fields) plus a literal APPLE_TEAM_ID — electron-builder's @electron/notarize integration auto-detects those three env vars with no extra config (hardened runtime + the JIT/unsigned-memory/disable-library-validation entitlements it needs are already electron-builder's defaults). If op isn't installed, the script falls back to an unnotarized build with a warning instead of failing outright; if op is installed but the item can't be resolved (locked vault, wrong item name), it fails loudly rather than silently shipping unnotarized — a signed-but-unnotarized build gets quarantined and blocked by Gatekeeper the moment it's downloaded (e.g. by electron-updater during an auto-update), which is exactly what broke a stale pre-rebrand install after the v0.3.0 release.