ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-12 21:53:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs(release): document complete extended-stable workflow (#112524)

Browse Source 
* docs(release): document extended-stable operations

* docs(release): tighten extended-stable guidance
This commit is contained in:
Dallin Romney
2026-07-23 10:48:48 +09:00
committed by GitHub
parent 9636f2aa2d
commit 7072c7f250
14 changed files with 357 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/openclaw-changelog-update/SKILL.md
+13 -4
View File
@@ -1,13 +1,14 @@
---
name: openclaw-changelog-update
description: Regenerate OpenClaw release changelog sections from git history before beta or stable releases.
description: Regenerate OpenClaw release changelog sections from git history before beta, stable, or extended-stable releases.
---
# OpenClaw Changelog Update
Use this for release changelog rewrites and GitHub release-note source text.
Run it once after the final Code SHA has green Full Release Validation. Do not
rerun it for same-candidate tooling retries, resumed publication, or promotion.
Use this for changelog rewrites and GitHub release-note source text. For regular
beta/stable, run it after the Code SHA passes Full Release Validation. For
extended-stable, run it before final exact-head validation and tagging. Do not
rerun it for tooling retries, resumed publication, or promotion.
Use it with `release-openclaw-maintainer`; this skill owns changelog content,
ordering, grouping, and attribution discipline.
@@ -253,6 +254,14 @@ every human `Thanks @...` attribution.
reuse enabled. It must select `changelog-only-release-v1`; any other changed
path returns the release to the Code SHA validation loop
## Extended-Stable Variant
Extended-stable has one release commit and no GitHub Release body. After version
prep and approved backports, regenerate `## YYYY.M.P` with the regular manifest
and original-main-PR provenance rules. Land it by PR, then validate the final
branch tip before tagging. Re-audit after a product backport; a tooling-only
repair needs no changelog entry. Never rewrite a published tag or changelog.
## Quota / API Outage Rule
If GitHub API quota is exhausted, do not idle. Continue work that does not need
.agents/skills/openclaw-testing/SKILL.md
+12 -4
View File
@@ -309,6 +309,12 @@ node scripts/full-release-validation-at-sha.mjs \
--target-ref release/YYYY.M.PATCH
```
That helper is for regular releases. Extended-stable dispatches Full Release
Validation directly from and against `extended-stable/YYYY.M.33` with
`release_profile=stable`; its exact branch-tip evidence is fresh and cannot be
replaced by a `release-ci/*` run. Use `$release-openclaw-ci` for its failure
classification and run-identity rules.
The helper pins the trusted workflow revision on current `main` while targeting
the historical release SHA and recording the canonical release branch as
context. It infers `beta` for alpha/beta package versions and `stable` for
@@ -654,9 +660,10 @@ Npm candidate selection:
- For stable package proof, use `package_spec=openclaw@latest` only when the
question is explicitly the current stable dist-tag; otherwise pin the exact
version.
- `source=npm` only accepts registry specs for `openclaw@beta`,
`openclaw@latest`, or exact OpenClaw release versions. Do not pass semver
ranges, git refs, file paths, tarball URLs, or plugin package names there.
- `source=npm` only accepts registry specs for `openclaw@extended-stable`,
`openclaw@beta`, `openclaw@latest`, or exact OpenClaw release versions. Do
not pass semver ranges, git refs, file paths, tarball URLs, or plugin package
names there.
- If the candidate is a tarball URL, use `source=url` with `package_sha256`. If
it is an Actions tarball artifact, use `source=artifact`. If it is an
unpublished source candidate, use `source=ref` with a trusted ref or SHA.
@@ -680,7 +687,8 @@ Profiles:
Candidate sources:
- `source=npm`: `openclaw@beta`, `openclaw@latest`, or an exact release version.
- `source=npm`: `openclaw@extended-stable`, `openclaw@beta`,
`openclaw@latest`, or an exact release version.
- `source=ref`: pack `package_ref` using the trusted `workflow_ref` harness.
This intentionally separates old package commits from new workflow/test code.
- `source=url`: HTTPS `.tgz` plus required `package_sha256`.
.agents/skills/release-openclaw-announcement/SKILL.md
+16 -3
View File
@@ -1,11 +1,11 @@
---
name: release-openclaw-announcement
description: "Draft or post OpenClaw beta/stable Discord release announcements from changelog, GitHub release, registry, and validation evidence. Use when announcing a beta, stable release, release candidate, or asking what users should test after an OpenClaw release."
description: "Draft or post OpenClaw beta, stable, or extended-stable Discord release announcements from changelog, tag, registry, and validation evidence. Use when announcing a release, release candidate, or asking what users should test after an OpenClaw release."
---
# OpenClaw Release Announcement
Use with `release-openclaw-maintainer` after a beta or stable release is live.
Use with `release-openclaw-maintainer` after a release is live.
Use with `$discord-user-post` when actually posting to Discord as the logged-in
user.
@@ -13,7 +13,7 @@ user.
Before drafting focus areas, read real release evidence:
1. Current GitHub release body for the tag.
1. GitHub release body, or the immutable tag and publish run for extended-stable.
2. `CHANGELOG.md` section for the released base version.
3. Commits since the previous shipped version or the operator-specified base.
4. Registry/package metadata for the exact version and current dist-tag.
@@ -69,6 +69,19 @@ openclaw --version
Fresh installs still point to `https://openclaw.ai`.
For extended-stable, name the exact version and trailing month. Mention only
observable backports, and use:
```sh
openclaw update --channel extended-stable
openclaw --version
```
Do not add `--yes`: users moving from newer regular stable must see the downgrade
warning because older versions may not understand newer configuration. Link the
tag or changelog; do not imply a GitHub Release or inherit regular stable
macOS, Windows, ClawHub, `latest`, or website claims.
## Style
- Discord Markdown, no tables.
.agents/skills/release-openclaw-ci/SKILL.md
+33 -5
View File
@@ -34,10 +34,12 @@ Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a rele
fails, the parent cancels the remaining child matrix and prints the failed
job summary. Inspect that first red job instead of waiting for unrelated
matrix tails.
- Treat the product-complete pre-changelog commit as the Code SHA. Full product
validation and performance evidence bind to that SHA. The later Release SHA
may reuse those results only when it is a descendant whose complete changed
path set is exactly `CHANGELOG.md`.
- For regular beta/stable releases, treat the product-complete pre-changelog
commit as the Code SHA. Full product validation and performance evidence bind
to that SHA. The later Release SHA may reuse those results only when it is a
descendant whose complete changed path set is exactly `CHANGELOG.md`.
- Extended-stable validates one exact branch tip; it does not reuse the regular
Code-SHA/Release-SHA evidence model.
- In a sparse worktree or Testbox source sync, first confirm `package.json`,
`pnpm-lock.yaml`, and every source path the selected check reads. If any are
absent, that checkout cannot validate a release dependency or Docker lane:
@@ -170,6 +172,29 @@ Publish with `openclaw-release-publish.yml` using `release_profile=from-validati
unless a maintainer intentionally wants to cross-check a specific profile; the
publish workflow reads the effective profile from the full-validation manifest.
### Extended-stable validation
For `.33+`, dispatch from and target the canonical branch; the regular
SHA-pinned helper would produce a rejected `release-ci/*` identity:
```bash
gh workflow run full-release-validation.yml \
--ref extended-stable/YYYY.M.33 \
-f ref=extended-stable/YYYY.M.33 \
-f release_profile=stable
```
Accept only a complete `rerun_group=all` run whose branch, head/target SHAs,
manifest `workflowRef`, and package versions identify the same commit. Save its
successful `run_attempt` and require the final tag to resolve there. Reject
`release-ci/*`, current-main, narrow, and earlier-attempt evidence.
Product failures need an approved backport. Frozen-target tooling failures need
the smallest behavior-preserving repair. Provider, approval, runner, or log
races keep the candidate unchanged. Record repairs and superseded runs; any
branch change requires a new complete parent. Omit only an explicitly
unsupported frozen-target scenario, never a required behavior or package.
## Watch
Use the transition-only summary watcher instead of repeated raw polling:
@@ -237,7 +262,8 @@ include_android=true -f release_gate=true`.
Record:
- Code SHA and Release SHA
- release identity: Code/Release SHAs for regular releases; canonical branch,
exact SHA, and immutable tag for extended-stable
- evidence-reuse policy and complete changed-path set
- active full parent run URL, attempt, workflow SHA, and any superseded parent
with the exact replacement reason
@@ -245,6 +271,8 @@ Record:
- performance comparison result versus earlier releases when available
- targeted local proof commands
- provider-secret preflight result
- frozen-target compatibility repairs or omitted inapplicable scenarios, with
their source PRs and invariant
- known gaps or unrelated failures
For lessons and recovery patterns, read `references/release-ci-notes.md`.
.agents/skills/release-openclaw-mac/SKILL.md
+4
View File
@@ -7,6 +7,10 @@ description: "Run or recover OpenClaw macOS release signing, notarization, appca
Use with `$release-openclaw-maintainer`, `$release-openclaw-ci`, `$one-password`, and `$release-private` if it exists when stable macOS assets, release-ops mac preflight, notarization, appcast promotion, or mac release recovery is involved.
This is a regular stable-release skill. Do not invoke it for extended-stable;
that track does not inherit macOS assets, appcast promotion, or a GitHub Release
unless the current extended-stable release policy explicitly adds them.
## Credentials
- Resolve Peter-owned ASC item refs, key ids, issuer ids, and service-token provenance from `$release-private`.
.agents/skills/release-openclaw-maintainer/SKILL.md
+39 -59
View File
@@ -207,9 +207,9 @@ prepare-run <PR>`.
- Do not create beta-specific `CHANGELOG.md` headings. Beta releases use the
stable base version section, for example `v2026.4.20-beta.1` uses
`## 2026.4.20` release notes.
- When any beta or stable release is live, make a best-effort Discord
announcement using the configured secret workflow; do not block or roll back
the release if the announcement fails.
- When any beta, stable, or extended-stable release is live, make a best-effort
Discord announcement using the release-track-specific wording; do not block
or roll back the release if the announcement fails.
- When asked to announce on X, use `~/Projects/bird/bird` and follow the
release tweet style below.
@@ -222,10 +222,9 @@ maintenance patch, read
or publication work. Treat backport discovery and preparation as an ability of
this release skill, not as a separate release workflow.
The backport ability owns the complete mainline inventory, private-security
reconciliation, candidate decisions, maintainer approval, coordinated staging
PR, and proof handoff. After that PR lands, use the dedicated extended-stable sequence
below. Never route `.33+` through the regular beta/stable release sequence.
The backport flow covers mainline inventory, private-security reconciliation,
approval, the staging PR, and proof handoff. After it lands, use the sequence
below. Never route `.33+` through regular beta/stable release steps.
## Publish Gateway extended-stable releases
@@ -236,62 +235,43 @@ Docker Gateway images. Treat
`scripts/openclaw-npm-extended-stable-release.mjs`, and the release workflows
on pinned current `main` as the exact command and validation contract.
1. Check out the canonical `extended-stable/YYYY.M.33` branch after the
approved backport PR lands. Verify the root and every publishable official
plugin have the intended version, then generate and commit the complete
`## YYYY.M.P` `CHANGELOG.md` section before freezing its full 40-character
SHA. Unlike the regular Code-SHA flow, this npm-only candidate preflight
packages the frozen tree, so a matching non-empty changelog section is a
prerequisite, not post-validation release decoration. Backport the complete
current-main Docker release-channel change, including its workflow, promoter,
policy, shared release-version classifier, tests, and workflow validation
changes. Do not create the final tag yet; tag-push workflows use that code,
which must not route `.33+` to regular stable aliases or fail from a partial
copy.
2. Dispatch `openclaw-npm-release.yml` from that canonical branch with the
frozen SHA as `tag`, `preflight_only=true`, and
`npm_dist_tag=extended-stable`. A full SHA is a validation-only candidate
input; save the successful preflight run ID and SHA.
3. Run Full Release Validation against the same frozen SHA with the canonical
branch as `target_context_ref`. Use
`node scripts/full-release-validation-at-sha.mjs --sha <sha> --target-ref extended-stable/YYYY.M.33`
so trusted workflow code is pinned independently from the exact product
target. Save the successful run ID and its exact `run_attempt` from
`gh api repos/openclaw/openclaw/actions/runs/<run-id> --jq .run_attempt`.
4. If either candidate gate fails or another backport is needed, update the
canonical branch and its matching `CHANGELOG.md` section, freeze its new
SHA, and rerun the affected gates. Do not create, delete, or move a final
`vYYYY.M.P` tag for candidate validation.
5. Only after the candidate gates are green, re-resolve the canonical branch
tip and require it still equals the validated SHA. Create and push the
signed final `vYYYY.M.P` tag at that SHA. Never move or delete a final
extended-stable tag: a post-tag code change needs a new patch version and a
new candidate.
1. On `extended-stable/YYYY.M.33`, verify the root and every publishable official
plugin have the intended version. Generate and commit the complete
`## YYYY.M.P` changelog section with `### Highlights`, `### Changes`, and
`### Fixes`. Carry the full current-main Docker
release-channel unit: workflow, promoter, policy, shared classifier, tests,
and workflow validation. Run focused checks and freeze the untagged tip SHA.
2. From that branch, run npm preflight with the SHA as `tag`,
`preflight_only=true`, and `npm_dist_tag=extended-stable`; save the run ID.
3. Run complete Full Release Validation from and against the canonical branch
with `release_profile=stable`; save its run ID and successful `run_attempt`.
Any branch change invalidates both gates.
4. Require the tip still equals the frozen SHA, then create signed `vYYYY.M.P`.
Never move or delete a final tag; later source changes need a new patch.
5. Require the saved validation run to be complete, successful, and bound to
the canonical branch, tag SHA, and attempt. Reject `release-ci/*` and narrow
reruns.
6. Dispatch `plugin-npm-release.yml` from the same branch with
`publish_scope=all-publishable`, the full release SHA as `ref`, and
`npm_dist_tag=extended-stable`. Require complete exact-version and selector
readback, then save the successful plugin run ID.
7. Dispatch the real `openclaw-npm-release.yml` publish from the same branch
with the intended tag, `npm_dist_tag=extended-stable`, all three saved run
IDs, and `full_release_validation_run_attempt=<saved-attempt>`. The workflow
must publish the exact prepared core tarball and prove the referenced runs
match the canonical branch and release SHA.
8. Independently verify the exact core package, every official plugin package,
and all `extended-stable` selectors. If only the core selector readback
fails, use the `openclaw` repair command generated by the core workflow. If
an official-plugin selector is missing or stale for an already-published
version, use the approved credential-isolated release tooling for manual
plugin tag repair; the OIDC source workflow cannot mutate that tag. Never
republish the same version.
9. Require `Docker Release` to publish and verify the exact default, slim,
browser, and architecture images in both registries before its final step
promotes the three extended-stable aliases through the shared promotion
script. For alias repair, dispatch
`docker-channel-promote.yml` from current `main` with the exact tag; never
rebuild or move the release tag.
10. Do not create a GitHub Release or publish the macOS app, Windows Hub,
mobile apps, website downloads, ClawHub packages, or private dist-tag
artifacts from this path.
7. Publish core from the same branch with the tag, `npm_dist_tag=extended-stable`,
all three run IDs, and the saved validation attempt. Require the prepared
tarball and every run to match the branch and release SHA.
8. From a clean current-`main` checkout, run
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P`.
Verify signatures, provenance, inventories, exact versions, and selectors.
Use the generated repair only for the root selector; repair other selectors
with approved credential-isolated tooling. Never republish a version.
9. Require `Docker Release` to verify default, slim, browser, and architecture
images in GHCR and Docker Hub, including attestations and platform versions.
It must advance only
`extended-stable`, `extended-stable-slim`, and `extended-stable-browser` by
digest and refuse automatic rollback. For alias repair, dispatch the
approval-gated `docker-channel-promote.yml` from current `main` with the exact
tag; never rebuild or move the release tag.
10. Do not create a GitHub Release or publish macOS, Windows, mobile, website,
ClawHub, or private dist-tag artifacts from this path.
## Keep release channel naming aligned
.agents/skills/release-openclaw-maintainer/references/extended-stable-backports.md
+25 -16
View File
@@ -21,9 +21,9 @@ extended-stable package and publication constraints.
- Cover the core `openclaw` package and every npm-publishable official plugin
included by the canonical `all-publishable` release inventory at the same
exact version.
- Carry the complete current-main Docker release-channel change in the tagged
tree, including its workflow, promoter, policy, shared release-version
classifier, tests, and workflow validation changes.
- Carry the complete current-main Docker release-channel unit in the tagged
tree: workflow, promoter, policy, shared release-version classifier, tests,
and workflow validation. GitHub evaluates tag-push workflows from that tree.
- Exclude ClawHub publication, GitHub Releases, the macOS app, Windows Hub,
mobile apps, website downloads, and private-repository dist-tags.
- Review the complete mainline delta using the shared evidence-driven audit.
@@ -245,7 +245,7 @@ ledger and release set before changing branches.
per fix, then combined changed-surface and release-relevant checks. Use
Crabbox/Testbox for broad, package, cross-OS, release, or E2E proof.
5. Set the intended root version and run `pnpm release:prep` on the same staging
branch. Verify every publishable official extension package has that exact
branch. Verify every publishable official plugin package has that exact
version. Do not create the tag or dispatch publication before the PR lands.
6. Run `$autoreview` until no accepted/actionable findings remain.
7. Open one coordinated PR targeting the canonical extended-stable branch.
@@ -261,6 +261,20 @@ unresolved blocked candidates so the next run carries them forward. Dispatch
npm preflight only after the canonical branch or tag has that exact final
version and SHA.
## Stabilize the landed candidate
Keep product backports separate from release-tooling compatibility. After the
coordinated PR lands:
1. Verify the branch tip, root/plugin versions, and complete Docker
release-channel unit identify one candidate.
2. Run focused proof, npm preflight, and complete branch-owned validation.
3. Use another approved PR for product defects; use the smallest
behavior-preserving repair for frozen-target tooling; retry external failures
without changing the candidate.
4. Record repairs and omitted unsupported scenarios. Any branch change requires
new exact-head evidence. Tag only the final green tip.
## Handoff
Report:
@@ -271,18 +285,13 @@ Report:
- included, skipped, blocked, not-affected, and already-covered candidates;
- affected core/plugin packages, adaptations, and commit order;
- proof commands, run IDs, and autoreview result;
- candidate-stabilization failures, their classification, every workflow or
harness compatibility repair, and superseded validation runs;
- remaining security, release, or maintainer approvals;
- the coordinated PR URL or why no PR was opened;
- explicit confirmation that no non-npm publication is planned.
- exact intended Docker images and aliases, plus explicit confirmation that no
other non-npm publication is planned.
After the PR lands, continue with this skill's canonical extended-stable
release flow. Require exact branch-tip/tag/package identity; run npm preflight
and Full Release Validation from the canonical branch; publish every
npm-publishable official plugin from the exact release SHA; publish the
prepared core tarball with the referenced successful run IDs; verify every
exact package and `extended-stable` selector; and preserve the generated
core `openclaw` selector-repair command. Repair missing or stale official-
plugin selectors on already-published versions with the approved credential-
isolated release tooling for manual tag repair; the OIDC source workflow cannot
mutate those tags. Never republish the same version when only a selector
needs repair.
Then follow the parent skill's publish and recovery sequence. Keep exact
branch/tag/package/run identity, never republish for selector repair, and move
only the `extended-stable*` Docker aliases.
.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md
+17 -7
View File
@@ -10,20 +10,27 @@ Ship `<version>` on `<channel>` and stop when `<terminal success criteria>`.
## Immutable state
- branch: `release/<YYYY.M.PATCH>`
- track: `<regular beta/stable | extended-stable>`
- branch: `<release/YYYY.M.PATCH | extended-stable/YYYY.M.33>`
- cut SHA: `<full sha>`
- Code SHA: `<full sha or not frozen>`
- Release SHA: `<full sha or not frozen>`
- Code SHA: `<regular release full sha | not applicable>`
- Release SHA: `<regular release full sha | exact extended-stable branch tip>`
- tag: `v<version>`
- workflow ref: `<release-ci ref | canonical branch>`
- publication inventory: `<exact surfaces>`
- approved backports: `<none or exact PRs/commits>`
- approved main changes: `<none or exact blocker>`
- frozen-target compatibility repairs: `<none or exact PRs/invariants>`
## Active evidence
- Full Release Validation parent: `<run id / attempt / URL or none>`
- npm preflight: `<run id / URL or none>`
- Plugin NPM Release: `<run id / URL or none>`
- publish parent: `<run id / URL or none>`
- Docker release/repair: `<run ids / tag / aliases or none>`
- immutable successful children: `<run ids / artifacts or none>`
- registry/provenance readback: `<artifact or command result>`
## Phase
@@ -33,10 +40,13 @@ Ship `<version>` on `<channel>` and stop when `<terminal success criteria>`.
## Failure policy
- product/code failure: fix the release branch, freeze a new Code SHA, and
invalidate downstream product evidence
- changelog-only failure: change only `CHANGELOG.md`, freeze a new Release SHA,
and reuse green Code SHA evidence after delta proof
- regular product/code failure: fix the release branch, freeze a new Code SHA,
and invalidate downstream product evidence
- regular changelog-only failure: change only `CHANGELOG.md`, freeze a new
Release SHA, and reuse green Code SHA evidence after delta proof
- extended-stable branch change: land the approved product/changelog change or
smallest frozen-target repair by PR, record its source/invariant, and replace
all exact-head evidence
- workflow/tooling/credential failure: keep the candidate frozen and recover
the smallest owning surface
- external approval or permission blocker: stop with the exact job, URL,
.agents/skills/release-openclaw-plugin-testing/SKILL.md
+17
View File
@@ -117,6 +117,23 @@ Use `source=npm -f package_spec=openclaw@beta` for published beta proof. Keep
`workflow_ref` as trusted current harness code unless the release process says
otherwise.
For extended-stable, branch-owned Full Release Validation is publication
evidence; Package Acceptance is a post-publish selector smoke:
```bash
gh workflow run package-acceptance.yml \
--repo openclaw/openclaw \
--ref main \
-f workflow_ref=main \
-f source=npm \
-f package_spec=openclaw@extended-stable \
-f suite_profile=package \
-f telegram_mode=mock-openai
```
Record the resolved version. Still verify every package and selector in the
tag's `all-publishable` inventory; one smoke is not registry readback.
## Plugin npm Artifact Preflight
Use the trusted `main` workflow to prepare and read back a selected plugin npm
.agents/skills/verify-release/SKILL.md
+47 -4
View File
@@ -1,6 +1,6 @@
---
name: verify-release
description: "Verify an OpenClaw release is fully published across GitHub, npm, plugins, ClawHub, package smoke, and live Gateway agent turns."
description: "Verify regular or extended-stable OpenClaw releases against the exact publication surfaces, workflow identities, package provenance, smoke tests, and live Gateway behavior expected for that release track."
---
# Verify Release
@@ -13,6 +13,9 @@ publish skill; use `$release-openclaw-maintainer` before changing release state.
- Resolve short suffixes like `.27` to the concrete CalVer version from the
current date/context, then say the resolved version.
- Resolve the track first. Regular beta/stable uses a GitHub Release and the
platform graph; extended-stable uses its canonical branch, npm selector, and
Gateway surfaces. Do not require one track's artifacts from the other.
- Verify live state. Do not trust local checkout state, release notes, or old
memory as current truth.
- If the checkout is dirty or divergent, use it only for scripts/reference.
@@ -21,7 +24,9 @@ publish skill; use `$release-openclaw-maintainer` before changing release state.
- Never print secrets. Use inherited live keys only for scoped smoke commands.
- Keep the final terse: `yes/no`, evidence bullets, caveats, cleanup.
## Core Checks
## Regular beta/stable checks
Use these checks only for the regular orchestrated release track.
1. GitHub release:
- `gh release view v<VERSION> --repo openclaw/openclaw --json tagName,name,publishedAt,isDraft,isPrerelease,targetCommitish,url,body,assets`
@@ -68,12 +73,48 @@ publish skill; use `$release-openclaw-maintainer` before changing release state.
soak, and blocking performance evidence.
- Summarize only relevant successful/failed jobs; ignore routine skipped
optional lanes unless the release body promised them.
6. Published package smoke:
## Extended-stable checks
Extended-stable has no GitHub Release ledger. Verify live tag, workflow,
registry, provenance, and image state directly.
1. **Identity:** require final `v<VERSION>` at patch `33+`, with no suffix,
contained in `extended-stable/YYYY.M.33`. Only an active candidate must equal
the tip. Root and every publishable official plugin must declare `<VERSION>`.
Require the Git tag and no GitHub Release.
2. **Workflow chain:** find successful preflight, complete validation, plugin
npm, and core publish runs on the canonical branch and SHA. Validation must
use `rerun_group=all`, `release_profile=stable`, blocking soak/performance,
and the saved attempt. Core publish must reference all three run IDs and bind
its manifest, workflow ref, and tarball digest to the release SHA.
3. **Registry:** require exact and `extended-stable` selectors to return
`<VERSION>` for root, every preflight `corePackageTarballs` entry, and every
`publishToNpm === true` official plugin derived from the tag. Compare the
plugin plan, jobs, and complete readback; never infer inventory from diffs.
4. **Provenance:** from trusted current tooling, run
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts <VERSION>`.
Require signatures, canonical-branch provenance, and publish/preflight
digest binding to the release SHA. Preserve output and workflow URLs.
5. **Docker:** verify exact default, slim, browser, and architecture images and
attestations in both registries. Only the three `extended-stable*` aliases may
resolve to those digests. Repair aliases through current-main `Docker Channel
Promotion` for the exact tag, without rebuilding.
6. **Recovery:** never republish. Use the generated command only for the root
selector and approved credential-isolated tooling for others, then repeat
complete readback. Do not require ClawHub, native/mobile apps, website,
private dist-tags, regular `latest`, or a GitHub Release.
## Shared live smoke
After the track-specific publication checks pass:
1. Published package smoke:
- In `/tmp`, isolated HOME:
`npm exec --yes --package openclaw@<VERSION> -- openclaw --version`.
- Run at least one harmless command that touches the published CLI surface,
for example `plugins --help` or `gateway --help`.
7. Dev Gateway live model smoke:
2. Dev Gateway live model smoke:
- Use temp HOME/workspace, not the user's normal state:
`HOME=/tmp/openclaw-release-smoke/home OPENCLAW_WORKSPACE=/tmp/openclaw-release-smoke/work pnpm openclaw --dev gateway run --auth none --force --verbose`.
- Health check via CLI: `openclaw --dev gateway health --json`.
@@ -89,6 +130,8 @@ publish skill; use `$release-openclaw-maintainer` before changing release state.
- Dist-tag caveat: stable `latest` is release truth; if optional `beta` mirrors
still point at a beta version, report it as a caveat, not a stable-release
blocker, unless the user asked to verify beta promotion.
- Track caveat: name the track and intentionally absent surfaces. Do not call
missing regular-release artifacts an extended-stable failure.
- Divergent checkout caveat: say when local source SHA differs from release tag
or origin and which live sources were used instead.
- Smoke caveat: distinguish Gateway-backed agent success from local embedded
docs/ci.md
+9 -9
View File
@@ -164,15 +164,15 @@ gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_andro
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
```
The monthly Gateway extended-stable path is the exception: dispatch both `OpenClaw NPM
Release` preflight and `Full Release Validation` from the exact
`extended-stable/YYYY.M.33` branch, preserve their run IDs, and pass both IDs to the
direct npm publish run. See [Monthly Gateway extended-stable
publication](/reference/RELEASING#monthly-gateway-extended-stable-publication) for
the commands, exact identity requirements, registry readback, and selector
repair procedure. It publishes the `openclaw` npm package, official npm plugins,
and Gateway Docker images. It does not publish the macOS app, Windows Hub,
mobile apps, a GitHub Release, ClawHub packages, or website artifacts.
Gateway extended-stable runs npm preflight, Full Release Validation, and plugin
npm release from `extended-stable/YYYY.M.33`; core publish consumes those three
run IDs plus the validation attempt. `release-ci/*` evidence is invalid because
publish binds every run to the canonical branch and release SHA. The tag
publishes Gateway images and only the `extended-stable*` aliases; the path skips
the regular orchestrator and its ClawHub, native-app, GitHub Release, website,
and private dist-tag surfaces. See [Monthly Gateway extended-stable
publication](/reference/RELEASING#monthly-gateway-extended-stable-publication)
for commands and recovery.
## Runners
docs/docs_map.md
+4
View File
@@ -8756,6 +8756,9 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- H2: Version naming
- H2: Release cadence
- H2: Monthly Gateway extended-stable publication
- H3: Prepare and stabilize the candidate
- H3: Publish the npm packages
- H3: Verify and recover
- H2: Regular release operator checklist
- H2: Stable main closeout
- H2: Release preflight
@@ -8827,6 +8830,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Route: /reference/full-release-validation
- Headings:
- H2: Extended-stable exception
- H2: Top-level stages
- H2: Release checks stages
- H2: Docker release-path chunks
docs/reference/RELEASING.md
+88 -97
View File
@@ -1,4 +1,5 @@
---
doc-schema-version: 1
summary: "Release lanes, operator checklist, validation boxes, version naming, and cadence"
title: "Release policy"
read_when:
@@ -7,18 +8,16 @@ read_when:
- Looking for version naming and cadence
---
OpenClaw currently exposes three user-facing update channels:
OpenClaw exposes four user-facing update channels:
- stable: the existing promoted release channel, which still resolves through npm `latest` until the separate CLI/channel milestone lands
- beta: prerelease tags that publish to npm `beta`
- stable: the promoted regular release on npm `latest`
- extended-stable: the trailing completed month's `.33+` maintenance line on
npm `extended-stable`
- beta: prerelease tags on npm `beta`
- dev: the moving head of `main`
Operators can publish the trailing completed month's Gateway distribution to
`extended-stable` beginning at patch `33`. This includes the `openclaw` npm
package, official npm plugins, and matching Docker Gateway images. It does not
publish the macOS app, Windows Hub, mobile apps, a GitHub Release, ClawHub, or
website downloads, and it does not move npm `latest`, Docker `latest`/`main`,
or the CLI update channel.
Extended-stable ships the trailing month's Gateway, official npm plugins, and
Docker images without moving regular `latest` or `main` selectors.
Tideclaw alpha builds are a separate internal prerelease track (npm dist-tag `alpha`), covered under [NPM workflow inputs](#npm-workflow-inputs) and [Release test boxes](#release-test-boxes).
@@ -36,7 +35,8 @@ Tideclaw alpha builds are a separate internal prerelease track (npm dist-tag `al
- `latest` continues to follow the current regular/daily npm line; `beta` is the current beta install target
- `extended-stable` means the supported trailing-month Gateway distribution, beginning at patch `33`; patch `34` and later are maintenance releases on that monthly line
- Regular final and regular correction releases publish to npm `beta` by default; release operators can target `latest` explicitly, or promote a vetted beta build later
- The monthly Gateway extended-stable path publishes the `openclaw` npm package and every npm-publishable official plugin at one version. Its tag publishes Docker Gateway images to GHCR and Docker Hub and moves only `extended-stable`, `extended-stable-slim`, and `extended-stable-browser`. It excludes the macOS app, Windows Hub, mobile apps, ClawHub, GitHub Releases, private dist-tags, and website downloads.
- Gateway extended-stable publishes core, every npm-publishable official plugin,
and its Docker images at one exact version; see the dedicated workflow below.
- Every regular final release ships the npm package, macOS app, signed standalone Android APK, and signed Windows Hub installers together. Beta releases normally validate and publish the npm/package path first, with native app build/sign/notarize/promote reserved for regular final unless explicitly requested.
## Release cadence
@@ -48,36 +48,31 @@ Tideclaw alpha builds are a separate internal prerelease track (npm dist-tag `al
## Monthly Gateway extended-stable publication
This is a dedicated exception to the regular release procedure below. For a
completed month `YYYY.M`, create `extended-stable/YYYY.M.33`; publish
`vYYYY.M.33` and later maintenance patches from that same branch. The release
tag, branch tip, checkout, package version, npm preflight, and Full Release
Validation run must all identify the same commit. Protected `main` must
already contain a strictly later calendar month's final version below patch
`33`; maintenance patches stay eligible after `main` advances by more than one
month.
For completed month `YYYY.M`, create `extended-stable/YYYY.M.33` and publish
`.33+` from that branch. Tag, branch, checkout, package version, preflight, and
validation must identify one commit. Before `.33`, protected `main` must contain
a later month's final version below patch `33`; later maintenance patches remain
eligible.
On the exact extended-stable branch, bump the root package to `YYYY.M.P`, run
`pnpm release:prep`, and verify every publishable plugin package has the same
version. Generate a complete `## YYYY.M.P` section in `CHANGELOG.md` with the
required `### Highlights`, `### Changes`, and `### Fixes` headings, then commit
and push all generated changes. The npm preflight packages that exact tree and
rejects a missing or empty matching release section. Freeze and record the
resulting full SHA; the workflows do not bump versions, synchronize packages,
or create release notes for you. Do not create the final tag for a candidate.
### Prepare and stabilize the candidate
Before running candidate gates, backport the complete Docker release-channel
change from current `main` as one tested unit. Its runtime files include
`.github/workflows/docker-release.yml`,
`scripts/docker-channel-promote.mjs`,
`scripts/lib/docker-release-policy.mjs`, and
`scripts/lib/release-version.mjs`; include the matching tests and workflow
validation changes too. Tag-push workflows run from the tagged commit, so a
partial or older copy can fail after building images or incorrectly move
regular `latest`/`main` aliases.
Audit the unaudited mainline range, reconcile private security work, approve a
bounded backport set, and land one coordinated PR. Do not push the canonical
branch directly.
Run the npm preflight and Full Release Validation against that frozen SHA, then
save both run IDs and the successful Full Release Validation run attempt:
On the canonical branch, set `YYYY.M.P`, run `pnpm release:prep`, and require
that version in every publishable official plugin. From the approved ledger,
generate and commit a complete `## YYYY.M.P` section with `### Highlights`,
`### Changes`, and `### Fixes`, citing original merged `main` PRs for equivalent
backports. Preflight rejects a missing or empty section.
Carry the full current-main Docker release-channel unit: workflow, promoter,
policy, shared classifier, tests, and workflow validation. GitHub loads tag
workflows from the tagged commit; an incomplete copy can fail after building or
move regular aliases. Run focused checks.
Freeze the full branch-tip SHA. Before tagging, preflight its exact npm bytes
and run Full Release Validation against that SHA:
```bash
RELEASE_SHA="$(git rev-parse HEAD)"
@@ -88,36 +83,32 @@ gh workflow run openclaw-npm-release.yml \
-f preflight_only=true \
-f npm_dist_tag=extended-stable
node scripts/full-release-validation-at-sha.mjs \
--sha "$RELEASE_SHA" \
--target-ref extended-stable/YYYY.M.33
gh workflow run full-release-validation.yml \
--ref extended-stable/YYYY.M.33 \
-f ref=extended-stable/YYYY.M.33 \
-f release_profile=stable
```
The SHA form is supported only by validation-only npm preflight. The helper
pins trusted workflow code while recording the exact product SHA and canonical
branch context. Its stable validation profile is separate from the npm
`extended-stable` dist-tag.
The SHA form is preflight-only. Run validation on the canonical branch; publish
binds its workflow ref, head/target SHA, run ID, and attempt. Save both IDs and
the successful `run_attempt`; reject `release-ci/*` evidence.
If either candidate gate fails or another backport is needed, update the branch
and its matching changelog section, freeze a new SHA, and rerun the affected
candidate gates. Do not create, delete, or move a final tag during candidate
validation. Once both gates are green, re-resolve the branch tip, require it
still equals `RELEASE_SHA`, then create and push signed `vYYYY.M.P` at that
SHA. A post-tag source change requires a new patch version and new candidate;
final extended-stable tags are never moved or deleted.
Classify failures before editing:
Pushing the tag starts `Docker Release`, which publishes version-specific
default, slim, browser, and architecture tags to both registries. It verifies their
attestations before promoting the three extended-stable aliases through the
shared promotion path. For alias-only repair, dispatch `Docker Channel
Promotion` from current `main` with the exact tag. It requires `docker-release`
approval and verifies source manifests, SBOMs, and provenance without
rebuilding images.
- Product: land another approved backport PR.
- Frozen-target tooling: backport only the smallest compatibility repair that
tests the old product unchanged.
- Provider, approval, runner, or service: keep the candidate unchanged and use
the bounded retry path.
After both runs succeed, publish every npm-publishable official plugin from the
same exact branch tip. Patch `P` must be `33` or greater. Pass the full release
SHA as `ref`, wait for the complete matrix and registry readback, then save the
successful Plugin NPM Release run ID:
Any branch change invalidates both gates. Once they pass, require the tip still
equals `RELEASE_SHA`, then push signed `vYYYY.M.P`. Later changes need the next
patch; never move or delete the tag. Its push starts `Docker Release`.
### Publish the npm packages
Publish every npm-publishable official plugin from the same SHA and save the
successful run ID:
```bash
RELEASE_SHA="$(git rev-parse HEAD)"
@@ -128,17 +119,10 @@ gh workflow run plugin-npm-release.yml \
-f npm_dist_tag=extended-stable
```
The workflow uses the regular prepared `all-publishable` package inventory,
including packages whose source did not change. It verifies every exact package
and every plugin `extended-stable` tag before succeeding. If a partial run
fails, rerun the same command: already-published packages are reused, missing
or stale plugin tags are reconciled under the npm release environment, and the
final readback still covers the complete package set.
The workflow covers all `all-publishable` packages, including unchanged ones,
and verifies every exact version and selector. Reruns reuse published versions.
After the plugin workflow succeeds and the npm release environment is ready,
publish the exact core preflight tarball. Core publication verifies that the
referenced plugin run is `completed/success` on the same canonical branch and
exact source SHA:
Then publish the prepared core tarball with all three saved run identities:
```bash
gh workflow run openclaw-npm-release.yml \
@@ -152,40 +136,46 @@ gh workflow run openclaw-npm-release.yml \
-f plugin_npm_run_id=<plugin-npm-run-id>
```
For a fork or non-production rehearsal that intentionally cannot satisfy the
monthly `.33` or protected-`main` month policy, add
`-f bypass_extended_stable_guard=true` to both npm preflight and publish
dispatches. The default is `false`. The bypass is accepted only with
`npm_dist_tag=extended-stable` and is recorded in the workflow summary. It
does not bypass the canonical `extended-stable/YYYY.M.33` workflow ref,
branch-tip/tag/checkout equality, final-tag syntax, package/tag version
equality, referenced run and manifest identity, tarball provenance,
environment approval, registry readback, or selector repair evidence.
For non-production rehearsal only, add
`-f bypass_extended_stable_guard=true` to preflight and publish. It bypasses the
month guard only, never canonical-ref, SHA/tag/version equality, provenance,
approval, or readback checks. Never use it for production.
The publish workflow verifies the referenced preflight, validation, and plugin
run identities, the prepared tarball digest, and the core registry selectors.
Independently confirm the result after the workflow succeeds:
### Verify and recover
From a separate clean current-`main` checkout, not the frozen branch, run:
```bash
node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.P
npm view openclaw@YYYY.M.P version --userconfig "$(mktemp)"
npm view openclaw@extended-stable version --userconfig "$(mktemp)"
```
Both commands must return `YYYY.M.P`. If publish succeeds but selector
readback fails, do not republish the immutable package version. Use the
single `npm dist-tag add openclaw@YYYY.M.P extended-stable` repair command
printed in the failed workflow's always-run summary, then repeat both
independent readbacks. Rollback to the prior selector is a separate operator
decision, not the readback repair path.
Require signatures and npm provenance for the canonical branch, plus publish,
preflight, and tarball-digest binding to the release SHA. Both commands must
return `YYYY.M.P`. Verify every prepared core package and `all-publishable`
official plugin at its exact version and selector.
Public support documentation initially designates Slack, Discord, and Codex as
covered extended-stable plugin surfaces. That list is a support statement, not
a release-code allowlist: every npm-publishable official plugin follows the
same exact-version publication path.
If only the root selector fails, use the generated
`npm dist-tag add openclaw@YYYY.M.P extended-stable` repair command printed in
the workflow summary. Repair existing plugin or other prepared-core selectors
through approved credential-isolated tooling; the OIDC source cannot mutate
them. Never republish an immutable version.
The regular checklist below continues to own beta, `latest`, GitHub Releases,
ClawHub, macOS, Windows, mobile apps, and the other platform release surfaces.
Do not run it for this Gateway extended-stable path.
Require `Docker Release` to verify exact default, slim, browser, and architecture
images in GHCR and Docker Hub, including attestations and platform versions. It
must advance only
`extended-stable`, `extended-stable-slim`, and `extended-stable-browser` by
digest; regular aliases remain unchanged and automatic rollback is rejected.
For alias repair, run approval-gated `Docker Channel Promotion` from current
`main` with the tag. It repeats digest, attestation, and platform checks, allows
an explicit rollback, and never rebuilds images.
Slack, Discord, and Codex are the initial documented support surfaces, not a
release allowlist: every npm-publishable official plugin ships. The regular
checklist alone owns beta/`latest`, GitHub Releases, ClawHub, native apps, mobile,
website, and private dist-tags; do not run those steps for this Gateway path.
## Regular release operator checklist
@@ -678,6 +668,7 @@ If a maintainer must fall back to local npm authentication, run any 1Password CL
- [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)
- [`.github/workflows/openclaw-release-checks.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-release-checks.yml)
- [`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-cross-os-release-checks-reusable.yml)
- [`.github/workflows/docker-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/docker-release.yml)
- [`scripts/resolve-openclaw-package-candidate.mjs`](https://github.com/openclaw/openclaw/blob/main/scripts/resolve-openclaw-package-candidate.mjs)
- [`scripts/openclaw-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/openclaw-npm-release-check.ts)
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
docs/reference/full-release-validation.md
+33 -7
View File
@@ -1,4 +1,5 @@
---
doc-schema-version: 1
summary: "Full Release Validation stages, child workflows, release profiles, rerun handles, and evidence"
title: "Full release validation"
read_when:
@@ -35,11 +36,33 @@ report that same workflow SHA. Pass
reachable from current `origin/main`. The workflow never creates or updates
repository refs itself.
When the Code SHA is green, generate and commit only `CHANGELOG.md`. This new
commit is the **Release SHA**. Run the same helper for the Release SHA. Product
evidence is reused only when GitHub proves the Release SHA descends from the
Code SHA and the complete changed path set is exactly `CHANGELOG.md`; npm
preflight and package/install acceptance still run on the Release SHA.
## Extended-stable exception
Extended-stable publish requires a run whose workflow and target are both the
canonical branch:
```bash
gh workflow run full-release-validation.yml \
--ref extended-stable/YYYY.M.33 \
-f ref=extended-stable/YYYY.M.33 \
-f release_profile=stable
```
Do not use `pnpm ci:full-release` or `release-ci/*`. Publish binds the run's
branch, head/target SHA, manifest `workflowRef`, ID, and attempt to the canonical
branch and release commit.
Backport product failures; make the smallest behavior-preserving repair for
frozen-target tooling; retry provider, approval, or runner failures without a
source change. Any branch change needs a complete new run. Do not omit required
package, installer, update, channel, or live behavior because the target is old.
For a regular release, when the Code SHA is green, generate and commit only
`CHANGELOG.md`. This new commit is the **Release SHA**. Run the same helper for
the Release SHA. Product evidence is reused only when GitHub proves the Release
SHA descends from the Code SHA and the complete changed path set is exactly
`CHANGELOG.md`; npm preflight and package/install acceptance still run on the
Release SHA.
`release_profile=stable` and `release_profile=full` always run the exhaustive
live/Docker soak. Pass `run_release_soak=true` to include the same soak lanes
@@ -272,8 +295,11 @@ Keep the `Full Release Validation` summary as the release-level index. It links
child run ids and includes slowest-job tables. For failures, inspect the child
workflow first, then rerun the smallest matching handle above.
Record both Code SHA and Release SHA, the reuse policy and changed-path set, the
green Code SHA parent run, and the lightweight Release SHA parent run.
For a regular release, record both Code SHA and Release SHA, the reuse policy
and changed-path set, the green Code SHA parent run, and the lightweight Release
SHA parent run. For extended-stable, record the canonical branch, exact release
SHA, fresh parent run id and attempt, workflow ref, every child run, and any
frozen-target compatibility repair or intentional omission.
Useful artifacts: