polymech/zeroclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
541c357002
zeroclaw/docs/release-process.md
jordanthejet 541c357002 docs: rewrite CI docs for simplified 4-workflow system 
Remove all references to deleted workflows (ci-run.yml, CI Required Gate,
sec-audit, pub-docker-img, pub-release, pub-homebrew-core, pr-intake-checks,
pr-labeler, pr-auto-response, pr-check-stale, pr-check-status, pr-label-policy,
workflow-sanity, main-promotion-gate, sec-codeql, sec-vorpal, etc.).

Rewrite docs to match the current 4 workflows:
- ci.yml (PR checks: test + build)
- release.yml (automatic beta release on push to master)
- ci-full.yml (manual full cross-platform build matrix)
- promote-release.yml (manual stable release)

Files rewritten:
- docs/ci-map.md — complete rewrite for current workflows
- docs/release-process.md — new two-tier release model (beta/stable)
- .github/workflows/main-branch-flow.md — simplified delivery flows
- .github/workflows/README.md — removed deleted helper scripts

Files updated (stale CI references removed):
- docs/pr-workflow.md
- docs/reviewer-playbook.md
- CONTRIBUTING.md
- Vietnamese locale sync: docs/vi/ and docs/i18n/vi/ (ci-map, pr-workflow,
  release-process, reviewer-playbook)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 17:35:04 -05:00

3.2 KiB
Raw Blame History

ZeroClaw Release Process

This runbook defines the maintainers' standard release flow.

Last verified: March 6, 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.

Release Model

ZeroClaw uses a two-tier release model:

  • Beta releases are automatic — every merge to master triggers a beta pre-release (vX.Y.Z-beta.<run_number>).
  • Stable releases are manual — a maintainer runs Promote Release via workflow dispatch to cut a non-pre-release version.

Workflow Contract

Release automation lives in:

  • .github/workflows/release.yml — automatic beta release on push to master
  • .github/workflows/promote-release.yml — manual stable release via workflow dispatch

Beta Release (automatic)

  • Triggered on every push to master.
  • Computes version from Cargo.toml: vX.Y.Z-beta.<run_number>.
  • Builds 5-target matrix (linux x86_64/aarch64, macOS x86_64/aarch64, Windows x86_64).
  • Publishes GitHub pre-release with archives + SHA256SUMS.
  • Builds and pushes multi-platform Docker image to GHCR (beta + version tag).

Stable Release (manual)

  • Triggered via workflow_dispatch with a version input (e.g. 0.2.0).
  • Validates version matches Cargo.toml and tag does not already exist.
  • Builds same 5-target matrix as beta.
  • Publishes GitHub stable release with archives + SHA256SUMS.
  • Builds and pushes Docker image to GHCR (latest + version tag).

Maintainer Procedure

1) Preflight on master

  1. Ensure CI is green on latest master.
  2. Confirm no high-priority incidents or known regressions are open.
  3. Confirm recent beta releases are healthy (check GitHub Releases page).

2) Optional: run CI Full Matrix

If verifying cross-compilation before a stable release:

  • Run CI Full Matrix manually (.github/workflows/ci-full.yml).
  • Confirms builds succeed on aarch64-unknown-linux-gnu, x86_64-apple-darwin, and x86_64-pc-windows-msvc.

3) Bump version in Cargo.toml

  1. Create a branch, update version in Cargo.toml to the target version.
  2. Open PR, merge to master.
  3. The merge triggers a beta release automatically.

4) Promote to stable release

  1. Run Promote Release workflow manually:
    • version: the target version (e.g. 0.2.0) — must match Cargo.toml
  2. Workflow validates version, builds all targets, and publishes.

5) Post-release validation

  1. Verify GitHub Release assets are downloadable.
  2. Verify GHCR tags for the released version.
  3. Verify install paths that rely on release assets (for example bootstrap binary download).

Standard Cadence

  • Patch/minor releases: weekly or bi-weekly.
  • Emergency security fixes: out-of-band.
  • Beta releases ship continuously with every merge.

Emergency / Recovery Path

If a stable release fails:

  1. Fix the issue on master.
  2. Re-run Promote Release with the same version (if the tag was not yet created).
  3. If the tag already exists, bump to the next patch version.

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.