diff --git a/.agents/skills/openclaw-changelog-update/SKILL.md b/.agents/skills/openclaw-changelog-update/SKILL.md index 05c91819215d..85ed8207209f 100644 --- a/.agents/skills/openclaw-changelog-update/SKILL.md +++ b/.agents/skills/openclaw-changelog-update/SKILL.md @@ -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 diff --git a/.agents/skills/openclaw-testing/SKILL.md b/.agents/skills/openclaw-testing/SKILL.md index ae11f6cb8345..b5b302e34ab3 100644 --- a/.agents/skills/openclaw-testing/SKILL.md +++ b/.agents/skills/openclaw-testing/SKILL.md @@ -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`. diff --git a/.agents/skills/release-openclaw-announcement/SKILL.md b/.agents/skills/release-openclaw-announcement/SKILL.md index d06f2d5ef7a5..2f7d05a20054 100644 --- a/.agents/skills/release-openclaw-announcement/SKILL.md +++ b/.agents/skills/release-openclaw-announcement/SKILL.md @@ -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. diff --git a/.agents/skills/release-openclaw-ci/SKILL.md b/.agents/skills/release-openclaw-ci/SKILL.md index 16d60b0d48d2..800d4ec10323 100644 --- a/.agents/skills/release-openclaw-ci/SKILL.md +++ b/.agents/skills/release-openclaw-ci/SKILL.md @@ -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`. diff --git a/.agents/skills/release-openclaw-mac/SKILL.md b/.agents/skills/release-openclaw-mac/SKILL.md index 1b7b17c32290..424f2b4ae9ea 100644 --- a/.agents/skills/release-openclaw-mac/SKILL.md +++ b/.agents/skills/release-openclaw-mac/SKILL.md @@ -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`. diff --git a/.agents/skills/release-openclaw-maintainer/SKILL.md b/.agents/skills/release-openclaw-maintainer/SKILL.md index 519d0281be09..bf87e0d9ab70 100644 --- a/.agents/skills/release-openclaw-maintainer/SKILL.md +++ b/.agents/skills/release-openclaw-maintainer/SKILL.md @@ -207,9 +207,9 @@ prepare-run `. - 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 --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/ --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=`. 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 diff --git a/.agents/skills/release-openclaw-maintainer/references/extended-stable-backports.md b/.agents/skills/release-openclaw-maintainer/references/extended-stable-backports.md index 2fe2bc0dbcda..dd1c0a20bf78 100644 --- a/.agents/skills/release-openclaw-maintainer/references/extended-stable-backports.md +++ b/.agents/skills/release-openclaw-maintainer/references/extended-stable-backports.md @@ -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. diff --git a/.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md b/.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md index 71589cf41acb..8fff78eb9cd9 100644 --- a/.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md +++ b/.agents/skills/release-openclaw-maintainer/references/release-handoff-template.md @@ -10,20 +10,27 @@ Ship `` on `` and stop when ``. ## Immutable state -- branch: `release/` +- track: `` +- branch: `` - cut SHA: `` -- Code SHA: `` -- Release SHA: `` +- Code SHA: `` +- Release SHA: `` - tag: `v` +- workflow ref: `` +- publication inventory: `` - approved backports: `` - approved main changes: `` +- frozen-target compatibility repairs: `` ## Active evidence - Full Release Validation parent: `` - npm preflight: `` +- Plugin NPM Release: `` - publish parent: `` +- Docker release/repair: `` - immutable successful children: `` +- registry/provenance readback: `` ## Phase @@ -33,10 +40,13 @@ Ship `` on `` and stop when ``. ## 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, diff --git a/.agents/skills/release-openclaw-plugin-testing/SKILL.md b/.agents/skills/release-openclaw-plugin-testing/SKILL.md index 47630c931cc2..02a7442a285a 100644 --- a/.agents/skills/release-openclaw-plugin-testing/SKILL.md +++ b/.agents/skills/release-openclaw-plugin-testing/SKILL.md @@ -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 diff --git a/.agents/skills/verify-release/SKILL.md b/.agents/skills/verify-release/SKILL.md index f1b1fc0e9cc2..3dc568e1c80d 100644 --- a/.agents/skills/verify-release/SKILL.md +++ b/.agents/skills/verify-release/SKILL.md @@ -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 --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` 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 ``. + 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 + `` 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 `. + 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@ -- 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 diff --git a/docs/ci.md b/docs/ci.md index 86b8aefb85fc..d5b2bf143274 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -164,15 +164,15 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -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 diff --git a/docs/docs_map.md b/docs/docs_map.md index 5c83f63b2c11..d3edcb9dc8b3 100644 --- a/docs/docs_map.md +++ b/docs/docs_map.md @@ -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 diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index 0845d95fa689..a05e4d63f800 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -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= ``` -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) diff --git a/docs/reference/full-release-validation.md b/docs/reference/full-release-validation.md index 957857bc6442..aca40be8d817 100644 --- a/docs/reference/full-release-validation.md +++ b/docs/reference/full-release-validation.md @@ -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: