Release Branches

OpenClaw can release from release/* while main carries larger refactors. Do not assume a green change on main is included in the next user-facing build.

Branch Reality

  • main is the integration line, not always the deployed release line.
  • release/* branches isolate critical fixes while main absorbs larger work such as internal API refactors.
  • Validate release-sensitive changes on the latest release branch and on main when both matter.
  • When a fix must be included in a release branch, call out the commit SHA, commit title, and why it belongs in that release.
  • Tag Peter on release inclusion requests so the release operator can make an explicit pick decision.
  • Keep the release branch clean. Do not use it as a second integration branch.

Release Notes And Changelog

  • Add CHANGELOG.md entries in the same commit when the change is user-visible, operationally meaningful, security-relevant, or release-note worthy.
  • Keep changelog entries factual and ordered by user impact.
  • Missing changelog ranges create release blindness. Backfills are useful, but they are weaker than writing the entry at the time of the change.
  • For normal contributor PR review in openclaw/openclaw, follow current repo guidance: release-note context may belong in the PR body or merge summary instead of direct changelog edits.

Core Release Shape

  • Beta releases come first.
  • Stable release happens after the latest beta has been checked manually.
  • Core openclaw npm publish uses GitHub OIDC trusted publishing from GitHub Actions.
  • Real npm publish requires a successful preflight run from the public repo main workflow.
  • Mac validation and publish are split from the public npm path so private signing and provider-key boundaries stay out of the public repo.
  • Dist-tag mutation is private workflow work. Do not fall back to local npm credentials.

Validation Expectations

  • Inspect relevant GitHub Actions runs manually when doing release work.
  • Do not trust a summarized green badge for release decisions.
  • Run or confirm release checks, package checks, install smoke checks, and platform-specific validation based on the surface touched.
  • Include the mac app in beta release thinking unless the release operator explicitly waives it.
  • Keep appcast.xml changes tied to the successful macOS publish artifact, not the version bump.

Failure Rules

  • If a publish path fails auth, fix the trusted publishing or environment configuration. Do not switch to local tokens.
  • If a release branch is missing a fix, pick the specific commit. Do not merge broad unrelated main drift.
  • If the previous release is broken and an install smoke test needs a known-good baseline, document the override and why it is safe.