openclaw/docs/reference/RELEASING.md

title, summary, read_when

title	summary	read_when
Release Policy	Public release channels, version naming, and cadence	Looking for public release channel definitions Looking for version naming and cadence

Release Policy

OpenClaw has three public release lanes:

• stable: tagged releases that publish to npm beta by default, or to npm latest when explicitly requested
• beta: prerelease tags that publish to npm beta
• dev: the moving head of main

Version naming

• Stable release version: YYYY.M.D
  • Git tag: vYYYY.M.D
• Stable correction release version: YYYY.M.D-N
  • Git tag: vYYYY.M.D-N
• Beta prerelease version: YYYY.M.D-beta.N
  • Git tag: vYYYY.M.D-beta.N
• Do not zero-pad month or day
• latest means the current promoted stable npm release
• beta means the current beta install target
• Stable and stable correction releases publish to npm beta by default; release operators can target latest explicitly, or promote a vetted beta build later
• Every OpenClaw release ships the npm package and macOS app together

Release cadence

• Releases move beta-first
• Stable follows only after the latest beta is validated
• Detailed release procedure, approvals, credentials, and recovery notes are maintainer-only

Release preflight

• Run pnpm build && pnpm ui:build before pnpm release:check so the expected dist/* release artifacts and Control UI bundle exist for the pack validation step
• Run pnpm release:check before every tagged release
• Run RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts (or the matching beta/correction tag) before approval
• After npm publish, run node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D (or the matching beta/correction version) to verify the published registry install path in a fresh temp prefix
• Maintainer release automation now uses preflight-then-promote:
  • real npm publish must pass a successful npm preflight_run_id
  • stable npm releases default to beta
  • stable npm publish can target latest explicitly via workflow input
  • stable npm promotion from beta to latest is still available as a separate manual workflow step
  • public macOS Release is validation-only
  • real private mac publish must pass successful private mac preflight_run_id and validate_run_id
  • the real publish paths promote prepared artifacts instead of rebuilding them again
• For stable correction releases like YYYY.M.D-N, the post-publish verifier also checks the same temp-prefix upgrade path from YYYY.M.D to YYYY.M.D-N so release corrections cannot silently leave older global installs on the base stable payload
• npm release preflight fails closed unless the tarball includes both dist/control-ui/index.html and a non-empty dist/control-ui/assets/ payload so we do not ship an empty browser dashboard again
• If the release work touched CI planning, extension timing manifests, or fast test matrices, regenerate and review the planner-owned checks-fast-extensions shard plan via node scripts/ci-write-manifest-outputs.mjs --workflow ci before approval so release notes do not describe a stale CI layout
• Stable macOS release readiness also includes the updater surfaces:
  • the GitHub release must end up with the packaged .zip, .dmg, and .dSYM.zip
  • appcast.xml on main must point at the new stable zip after publish
  • the packaged app must keep a non-debug bundle id, a non-empty Sparkle feed URL, and a CFBundleVersion at or above the canonical Sparkle build floor for that release version

Public references

• .github/workflows/openclaw-npm-release.yml
• .github/workflows/openclaw-npm-promote-beta.yml
• scripts/openclaw-npm-release-check.ts
• scripts/package-mac-dist.sh
• scripts/make_appcast.sh

Maintainers use the private release docs in openclaw/maintainers/release/README.md for the actual runbook.