Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Releasing

Signing setup

Before releasing, configure the repository’s signing environment to allow deployments only from main. Its ZIPSIGN_KEY secret must contain the base64-encoded 64-byte signing key pair matching crates/sirene/release.pub. The signing task refuses a mismatched key.

cargo xtask gen-key --out DIR writes a new release.key and release.pub. Keep the private release.key outside the repository and never commit it. The checked-in verifying key is crates/sirene/release.pub. For an existing release key, retain that pair; replacing it needs the key rotation steps, so older installations can still update.

Release steps

main carries the next -dev version between releases. CI’s semver job compares sirene-core’s API with its latest crates.io release; a change that breaks it also bumps the -dev version to the next minor (0.5.1-dev to 0.6.0-dev), so the release is numbered for it.

To release X.Y.Z:

  1. Set version in the root Cargo.toml, and the matching [workspace.dependencies] pins, to X.Y.Z.
  2. Add a ## [X.Y.Z] section to CHANGELOG.md.
  3. Merge to main.

.github/workflows/release.yml then runs CI and the RustSec audit, builds the binaries and Sirene.app. The sign job builds xtask before exposing the secret, decodes the key with umask 077, and signs the tarballs before their attestations and SHA256SUMS are generated. The wasm job builds sirene-wasm-X.Y.Z.tar.gz (Web pages) and attests it, and packs the @jaemk/sirene npm package. The release job creates the vX.Y.Z release with the signed tarballs, app, sirene-wasm tarball, and checksums. After approval in the release environment, publish publishes sirene-core, sirene-gui, and sirene to crates.io, commits the Homebrew formula, the cask, and the next -dev version to main, then publishes @jaemk/sirene to npm.

npm setup

npm publishing is trusted publishing only. On npmjs.com, @jaemk/sirene’s settings name the trusted publisher (GitHub Actions, jaemk/sirene, workflow release.yml, environment release) and set publishing access to require two-factor authentication and disallow tokens.

To retry a failed release, dispatch the release workflow from main. If the release already exists, main must still be at the commit named by its vX.Y.Z tag; the workflow refuses to rebuild that version from a different commit. Dispatches from other branches skip the release.

See spec/workspace.md (WORKSP-8, WORKSP-9) and spec/macos-packaging.md for the details.