buzz/RELEASING.md

Releasing Buzz

Buzz has three independent release lanes, each driven by a release PR — no human ever pushes a git tag:

Lane	Recipe	Artifact
Desktop	just release-desktop	Signed desktop app (macOS/Linux)
Relay	just release-relay	ghcr.io/block/buzz container image
Mobile	just release-mobile	Buzz mobile app (tag is the sprout_ref for the internal build)

The three lanes version independently: the desktop version lives in desktop/package.json, the relay version in crates/buzz-relay/Cargo.toml, and the mobile version in mobile/pubspec.yaml.

The mobile lane publishes a mobile-v<version> tag that is consumed manually, cross-repo, as the sprout_ref input to the internal buzz-releases Buildkite pipeline (iOS dogfood → Block Comp Portal, App Store → TestFlight — see Internal Releases). The OSS lane is tag-only by design: OSS block/buzz CI cannot trigger CI in the private buzz-releases repo (infosec), so a human cuts the internal build from the tag rather than auto-dispatching across that boundary.

Quick Start

# Desktop release (next patch version)
just release-desktop

# Desktop patch / minor / explicit
just release-desktop patch
just release-desktop 0.4.0
just release-desktop 1.0.0

# Relay release (same argument forms)
just release-relay
just release-relay 0.4.0

# Mobile release (same argument forms)
just release-mobile
just release-mobile 0.4.0

just release-desktop creates a version-bump/<version> PR; just release-relay creates a relay-release/<version> PR; just release-mobile creates a mobile-release/<version> PR. Each bumps its own version manifest, regenerates lockfiles, and appends a changelog entry. Merge the PR to trigger the build automatically (the mobile tag is instead the sprout_ref a human feeds the internal build — see above).

Re-running any of these recipes with the same version is safe — it detects the existing branch and PR, resets to current main, regenerates the changelog with any new commits, and updates the PR in place.

---

How It Works

All three lanes share one engine; they differ only in which version manifest they bump, which branch prefix they use, and what the merge triggers.

Desktop

1. just release-desktop runs locally on main — computes the next version, creates (or reuses) a version-bump/<version> branch, bumps the desktop manifests, regenerates lockfiles, generates a changelog entry in CHANGELOG.md, commits, pushes, and opens (or updates) a PR.
2. Merge the PR — the auto-tag-on-release-pr-merge workflow detects the version-bump/* branch merge and pushes a v<version> tag.
3. Tag triggers release.yml — builds, signs, notarizes, and publishes the desktop app for macOS and Linux.

Relay

1. just release-relay runs locally on main — computes the next relay version, creates (or reuses) a relay-release/<version> branch, bumps crates/buzz-relay/Cargo.toml, regenerates Cargo.lock, generates a changelog entry in crates/buzz-relay/CHANGELOG.md, commits, pushes, and opens (or updates) a PR.
2. Merge the PR — the auto-tag-on-release-pr-merge workflow detects the relay-release/* branch merge and pushes a relay-v<version> tag.
3. Auto-tag dispatches docker.yml — the same workflow then triggers docker.yml with the version and tag ref, which builds the multi-arch relay image and publishes ghcr.io/block/buzz:<version> (plus :<major>.<minor>, :<major>, and :latest for stable releases). Prereleases (relay-v<version>-rc.1) publish only the prerelease tag and do not move :latest. (The dispatch — rather than relying on docker.yml's push: tags trigger — is required because GitHub suppresses on: push for tags pushed by the workflow's own GITHUB_TOKEN; the desktop lane dispatches release.yml for the same reason.)

Every push to main continues to build and publish :main + :sha-<7> tags (the rolling development image). The :latest tag tracks the latest stable relay release only — it does not move on main pushes or prereleases.

Mobile

1. just release-mobile runs locally on main — computes the next mobile version, creates (or reuses) a mobile-release/<version> branch, bumps mobile/pubspec.yaml (preserving the +build number), regenerates mobile/pubspec.lock, generates a changelog entry in mobile/CHANGELOG.md, commits, pushes, and opens (or updates) a PR.
2. Merge the PR — the auto-tag-on-release-pr-merge workflow detects the mobile-release/* branch merge and pushes a mobile-v<version> tag.
3. The tag is consumed manually, cross-repo — nothing in OSS block/buzz builds on the tag (OSS CI must not trigger CI in the private buzz-releases repo — infosec). A human feeds the mobile-v<version> tag as the sprout_ref input to the internal buzz-releases Buildkite pipeline, which builds and ships iOS to Block Comp Portal (dogfood) and TestFlight (App Store, opt-in). See Internal Releases.

---

Release Types

The argument forms below apply to release-desktop, release-relay, and release-mobile:

Command	Version	Example
just release-desktop	Next patch	0.3.0 → 0.3.1
just release-desktop patch	Next patch	0.3.0 → 0.3.1
just release-desktop 0.4.0	Explicit minor	0.3.1 → 0.4.0
just release-desktop 1.0.0	Explicit	1.0.0

---

Version Files

just bump-desktop-version <version> (desktop lane) updates these files:

File	Field
desktop/package.json	"version"
desktop/src-tauri/tauri.conf.json	"version"
desktop/src-tauri/Cargo.toml	version (under [package])

It also regenerates pnpm-lock.yaml and desktop/src-tauri/Cargo.lock.

just bump-relay-version <version> (relay lane) updates crates/buzz-relay/Cargo.toml (version under [package]) and regenerates the workspace Cargo.lock.

just bump-mobile-version <version> (mobile lane) updates mobile/pubspec.yaml (version:, preserving the +build number) and regenerates mobile/pubspec.lock.

---

Manual Fallback

If the automated flow isn't suitable (e.g., building from a non-main ref):

1. Go to Actions > Release in the GitHub UI
2. Click Run workflow
3. Provide the semver version (no v prefix) and the ref to build from

---

Internal Releases

After the OSS release ships, trigger an internal build via the sprout-releases Buildkite pipeline. See the buzz-releases README for the full step-by-step instructions and input field reference.

---

What Gets Published

Each release produces two GitHub releases:

1. v<version> — the user-facing release with the .dmg installer (macOS).

2. buzz-desktop-latest — a rolling pre-release for the Tauri auto-updater containing latest.json, the signed .tar.gz archive, and its .sig signature.

---

Platform Support

The release workflow builds two separate macOS DMGs — Apple Silicon (darwin-aarch64, the release job) and Intel (darwin-x86_64, the release-macos-x64 job) — plus Linux .deb and .AppImage. Both macOS DMGs are codesigned, notarized, and attached to the same v<version> release. Intel users download the _x64.dmg.

---

Prerequisites

• Write access to the block/buzz GitHub repository
• gh CLI authenticated (gh auth status)
• The following GitHub Actions secrets must be configured:

  Secret	Purpose
  BUZZ_UPDATER_PUBLIC_KEY	Tauri updater public key (minisign)
  TAURI_SIGNING_PRIVATE_KEY	Tauri updater private key
  TAURI_SIGNING_PRIVATE_KEY_PASSWORD	Password for the private key

---

Troubleshooting

just release-desktop fails with "must be on main branch"

Switch to main and pull latest before running the release recipe.

just release-desktop fails with "working tree is dirty"

Commit or stash your changes before running the release recipe.

New commits merged after creating the release PR

Re-run the release recipe (just release-desktop, just release-relay, or just release-mobile) from an up-to-date main. It resets the branch to current main, regenerates the changelog and PR body to include the new commits, and force-pushes the updated branch.

Build fails at "Validate version"

The version string must be valid semver: MAJOR.MINOR.PATCH with an optional pre-release suffix. Do not include a v prefix.

Auto-updater reports "no update available"

Verify that the buzz-desktop-latest release exists and contains a valid latest.json. The auto-updater manifest currently lists darwin-aarch64 only, so Intel and Linux users do not yet receive auto-updates — they download new versions manually from the release page. (Adding their entries to latest.json is a follow-up.)