Skip to content

Latest commit

 

History

History
133 lines (88 loc) · 3.67 KB

release-process.md

File metadata and controls

133 lines (88 loc) · 3.67 KB

ZeroClaw Release Process

This runbook defines the maintainers' standard release flow.

Last verified: February 21, 2026.

Release Goals

  • Keep releases predictable and repeatable.
  • Publish only from code already in master.
  • Verify multi-target artifacts before publish.
  • Keep release cadence regular even with high PR volume.

Standard Cadence

  • Patch/minor releases: weekly or bi-weekly.
  • Emergency security fixes: out-of-band.
  • Never wait for very large commit batches to accumulate.

Workflow Contract

Release automation lives in:

  • .github/workflows/pub-release.yml
  • .github/workflows/pub-homebrew-core.yml (manual Homebrew formula PR, bot-owned)

Modes:

  • Tag push v*: publish mode.
  • Manual dispatch: verification-only or publish mode.
  • Weekly schedule: verification-only mode.

Publish-mode guardrails:

  • Tag must match semver-like format vX.Y.Z[-suffix].
  • Tag must already exist on origin.
  • Tag commit must be reachable from origin/master.
  • Matching GHCR image tag (ghcr.io/<owner>/<repo>:<tag>) must be available before GitHub Release publish completes.
  • Artifacts are verified before publish.

Maintainer Procedure

1) Preflight on master

  1. Ensure required checks are green on latest master.
  2. Confirm no high-priority incidents or known regressions are open.
  3. Confirm installer and Docker workflows are healthy on recent master commits.

2) Run verification build (no publish)

Run Pub Release manually:

  • publish_release: false
  • release_ref: master

Expected outcome:

  • Full target matrix builds successfully.
  • verify-artifacts confirms all expected archives exist.
  • No GitHub Release is published.

3) Cut release tag

From a clean local checkout synced to origin/master:

scripts/release/cut_release_tag.sh vX.Y.Z --push

This script enforces:

  • clean working tree
  • HEAD == origin/master
  • non-duplicate tag
  • semver-like tag format

4) Monitor publish run

After tag push, monitor:

  1. Pub Release publish mode
  2. Pub Docker Img publish job

Expected publish outputs:

  • release archives
  • SHA256SUMS
  • CycloneDX and SPDX SBOMs
  • cosign signatures/certificates
  • GitHub Release notes + assets

5) Post-release validation

  1. Verify GitHub Release assets are downloadable.
  2. Verify GHCR tags for the released version (vX.Y.Z) and release commit SHA tag (sha-<12>).
  3. Verify install paths that rely on release assets (for example bootstrap binary download).

6) Publish Homebrew Core formula (bot-owned)

Run Pub Homebrew Core manually:

  • release_tag: vX.Y.Z
  • dry_run: true first, then false

Required repository settings for non-dry-run:

  • secret: HOMEBREW_CORE_BOT_TOKEN (token from a dedicated bot account, not a personal maintainer account)
  • variable: HOMEBREW_CORE_BOT_FORK_REPO (for example zeroclaw-release-bot/homebrew-core)
  • optional variable: HOMEBREW_CORE_BOT_EMAIL

Workflow guardrails:

  • release tag must match Cargo.toml version
  • formula source URL and SHA256 are updated from the tagged tarball
  • formula license is normalized to Apache-2.0 OR MIT
  • PR is opened from the bot fork into Homebrew/homebrew-core:master

Emergency / Recovery Path

If tag-push release fails after artifacts are validated:

  1. Fix workflow or packaging issue on master.
  2. Re-run manual Pub Release in publish mode with:
    • publish_release=true
    • release_tag=<existing tag>
    • release_ref is automatically pinned to release_tag in publish mode
  3. Re-validate released assets.

Operational Notes

  • Keep release changes small and reversible.
  • Prefer one release issue/checklist per version so handoff is clear.
  • Avoid publishing from ad-hoc feature branches.