Vincent Koc
eb22357959
* docs(release): restore the npm publication bookmark
Preserve the published publish-the-npm-packages fragment after the extended-stable heading rename. Keep the current release policy and canonical maintainer procedures unchanged.
* docs(reference): split the release runbook by reader job
docs/reference/RELEASING.md was 99,140 characters and mixed reference,
how-to, and explanation content for five release jobs on one page. It is
now a 4.6k index over nine pages under docs/reference/releasing/, one per
reader job, so an operator can complete one procedure on one page.
Children, in release order:
- releasing/versioning - version formats, git tags, npm dist-tags, cadence
- releasing/preflight - checks and generators to run before tagging
- releasing/regular-release - the twelve-step operator checklist
- releasing/test-boxes - Full Release Validation and the Vitest, Docker,
QA Lab, and Package boxes
- releasing/publish-automation - OpenClaw Release Publish order, tooling
tags, and Windows, Android, and ClawHub recovery
- releasing/beta-latest-sequence - the orchestrated stable sequence
- releasing/main-closeout - bringing main to the shipped state
- releasing/extended-stable - the monthly .33+ Gateway lane
- releasing/npm-workflow-inputs - operator-controlled workflow inputs
Anchor strategy. Per-anchor routes are impossible here: redirectSource()
in scripts/lib/docs-redirects.mjs rejects any source containing [?#]. So
every original anchor stays alive on the parent index, matching the
configuration-reference, Control UI, CI, protocol, and Slack splits: 18
authored <a id="..." /> stubs in a "Where each section moved" list, each
linking to /reference/releasing/<child>#<anchor>. The remaining two ids,
public-references and related, keep their sections on the index itself
and are deliberately not stubbed, so no duplicate authored/canonical ID
is raised.
Every id was computed with parseDocsDocument from
scripts/lib/docs-markdown.mjs, never a slug approximation. That matters
for "Regular beta/latest stable release sequence", which mints both the
percent-encoded canonical regular-beta%2Flatest-stable-release-sequence
and the compatibility alias regular-beta/latest-stable-release-sequence;
both are stubbed.
Anchor proof, run as a script rather than inferred from a passing audit
(a split rewrites the repo's own links, so docs-link-audit reads clean
even when every external deep link is broken): 20 pre-split ids
enumerated, 20 resolve against the parsed post-split index through
resolveDocsFragment, 18 stubs all point at an id that exists on the named
child, 0 collisions on the index or any child.
Losslessness, asserted mechanically by concatenating child bodies back
to the original section bodies: 0 divergences. Words 12,605 -> 13,045
(+440 from the index funnel, per-child frontmatter, and Related blocks).
Code fences 23 -> 23, unchanged. Links 23 -> 79 (+18 stubs, +9 index
bullets, +27 Related entries, +2 orphan repairs). Characters 98,834 ->
104,528.
Prose was not rewritten. The one declared exception is the cross-
reference repair the split requires: "see the dedicated workflow below"
in Version naming and "documented at the top of this page" in the
beta/latest sequence both pointed at content that now lives on another
page, so each became a real link to the extended-stable page.
Supporting changes:
- docs/docs.json gains a "Release runbook" nav group under "Release
process", mirroring the "CI" group under "Testing and CI".
- .github/CODEOWNERS extends @openclaw/openclaw-release-managers to
/docs/reference/releasing/, so the split does not silently drop
release-manager ownership of the runbook.
- test/scripts/package-acceptance-workflow.test.ts and
test/scripts/openclaw-npm-extended-stable-workflow.test.ts read
RELEASING.md plus docs/reference/releasing/*.md as one set, following
the pattern already used there for docs/ci.md plus docs/ci/*.md, so the
assertions follow the content instead of a single file path.
- test/scripts/docs-sync-publish.test.ts pins the nine new routes.
- docs/.i18n/glossary.zh-CN.json gains one entry per new page title.
The zh-CN targets are machine-written and unreviewed.
Closes audit findings: r3-0683, r3-0685
* Merge origin/main into docs-audit/split-releasing
Five commits changed docs/reference/RELEASING.md while this branch was
turning it into an index (#142195, #142291, #142260, #141786, #140672),
adding 98 lines. Resolved to the index, then re-extracted every child
section from main's current file: 15 sections refreshed across 9
children. Verified line by line that all 792 content lines present on
main survive the split.
Re-extraction reverted three of the split's own repairs, which is the
known cost of that approach:
- four cross-page links fell back to same-page fragments
(#regular-release-publish-automation, #stable-main-closeout); all
repointed at the children that own those headings
- versioning.md's "see the dedicated workflow below" lost its target
again and is a link to /reference/releasing/extended-stable once more
The link reverts are caught by docs-link-audit and markdownlint MD051.
The prose revert is caught by nothing and was found by hand.
Glossary: union keyed on source, 701 entries, 0 duplicate sources.
Full CI docs gate after staging: markdownlint 0 issues,
docs-link-audit --anchors 0 broken links, check-docs-mdx passed,
format-docs clean.
Still requires @openclaw/openclaw-release-managers approval.
* docs(reference): stub the anchors main added, and relink extended-stable
Both found by ClawSweeper on the rebased head.
Main added three headings to RELEASING.md while this branch was open:
Previous updater compatibility, Design proposal: immutable runtime
generations, and Required checks. Re-extracting moved their content to
preflight.md but added no compatibility stubs, so links such as
/reference/RELEASING#previous-updater-compatibility lost their target.
Added four stubs — the punctuated heading emits both an encoded and a
cleaned id, and both are now covered.
Anchor preservation applies to content main adds mid-flight, not only to
what existed when the split was planned. Verified against main's current
file: 24 pre-split ids, 24 resolving on the index, 0 lost.
Also restored the second extended-stable cross-page link. The earlier
rebase reverted two of them; I fixed versioning.md but missed
beta-latest-sequence.md, which still said the path was "documented at
the top of this page" after that path moved to its own child. An
orphaned directional phrase passes every validator, which is why this
one survived a full gate run.
markdownlint 0 issues, docs-link-audit --anchors 0 broken links,
check-docs-mdx passed, format-docs clean.
* Merge origin/main into docs-audit/split-releasing
Glossary conflict only; union keyed on source, 709 entries, 0 duplicate
sources. No page conflicted.
Ran the new .audit/check-orphan-refs.py over this tree: 0 directional
references remaining. That check exists because this branch shipped two
orphaned 'below' references past a full gate run, and they were found by
a reviewer both times.
markdownlint 0 issues, docs-link-audit --anchors 0 broken links,
format-docs clean.
Still requires @openclaw/openclaw-release-managers approval.
* Merge origin/main into docs-audit/split-releasing
This PR has been waiting on release-manager review, and main moved under
it. Refreshed so it is mergeable the moment the owners approve.
#142538 added 41 lines on extended-stable validation dispatch to
docs/reference/RELEASING.md. Resolved to the index, then re-extracted
five child sections from main's current file so that content survives.
Verified line by line: 817 content lines on main, all present after the
split. The one apparent gap is the Tideclaw alpha line, which is present
with its link repointed at the npm-workflow-inputs child.
Re-extraction reverted the split's own repairs again, both kinds:
- four cross-page links fell back to same-page fragments and were
repointed at the children owning those headings
- two orphaned directional references came back and were relinked,
in versioning.md and beta-latest-sequence.md
The link reverts are caught by docs-link-audit; the prose reverts are
caught by nothing and were found with .audit/check-orphan-refs.py.
Anchor check against main's current file: 24 ids, 24 resolving, 0 lost.
markdownlint 0 issues, format-docs clean, check-docs-mdx passed.
docs-link-audit --anchors reports only the 3 pre-existing maturity
failures that also fail on a clean origin/main.
Still requires @openclaw/openclaw-release-managers approval.
* Merge origin/main into docs-audit/split-releasing
Three conflicts, resolved as follows.
docs/reference/RELEASING.md: kept the index (ours). main's only change to
this page since the merge base is ca3bc36e1b, which rewrote one paragraph
of the `update-first-hop-compat` lane inside "Release preflight". That
section now lives in docs/reference/releasing/preflight.md, so main's hunk
was applied there verbatim rather than dropped.
test/scripts/package-acceptance-workflow.test.ts: took main's version of
both hunks -- the recursive docs/ci walk and the new set-read over
docs/reference/full-release-validation/ -- and kept readReleasingDocs() as
the reader for the release policy page. readReleasingDocs() now walks
docs/reference/releasing recursively with toSorted(), matching the pattern
and the rationale main established for docs/ci.
docs/.i18n/glossary.zh-CN.json: order-preserving union. 1119 sources from
main + 10 from this branch = 1129, 0 duplicates, both sides' orders
preserved as subsequences. The 10 new entries were moved out of the
end-of-array collision zone to sit beside the parent "Release policy"
entry.
Losslessness re-proved against current origin/main:docs/reference/RELEASING.md
(body sha256 9159abcad8cc2afe9a823570ca852fe912f66ed27c6c85a40d6576c595c51230):
all 12 top-level sections are byte-identical once the 6 declared link
rewrites are reversed; concatenated sections hash
66734f4ef0c88c6f2a7153de8708a5a58c058ed1561843babcdd0dec77410104 on both
sides. Code fences 25 -> 25 with an identical (info string, body sha256)
multiset; 0 tables; words 14,179 -> 15,020.
* Merge remote-tracking branch 'origin/main' into docs-audit/split-releasing
* origin/main:
fix(channels): preserve labels for unloaded plugins (#143416)
refactor(tests): share image resource acquisition setup (#143443)
refactor(hooks): consolidate source precedence policy (#143439)
* docs(release): retain the original split history
The canonical release-policy split landed in #156946. Preserve the original branch ancestry while retaining only its missing legacy publication anchor on current source.
* commit 'f478156122dcc285acb7413024c4ecfc3101e0c8':
docs(reference): stub the anchors main added, and relink extended-stable
docs(reference): split the release runbook by reader job
Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
12 KiB
doc-schema-version, summary, title, read_when
| doc-schema-version | summary | title | read_when | |||
|---|---|---|---|---|---|---|
| 1 | OpenClaw release channels, version numbers, validation, and published assets | Release policy |
|
OpenClaw offers stable releases for everyday use, beta releases for testing, and extended-stable releases for users who prefer an older Gateway maintenance line. This page explains those choices and what a release has been checked for. For switching channels, see Release channels.
Release channels
| Channel | What you get |
|---|---|
| Stable | The regular release promoted to npm latest. |
| Beta | A candidate on npm beta. This may be a prerelease or a final version awaiting promotion. |
| Extended-stable | A Gateway maintenance release from either of the two trailing completed months, on npm extended-stable. |
| Dev | The moving head of main, for development. |
Extended-stable includes the Gateway, official npm plugins, and Docker images. It does not include native apps or ClawHub publication, and it does not change the regular stable channel. Its GitHub release is not marked Latest. A monthly line retires when it falls outside the two supported completed months.
Alpha builds are a separate internal testing track, not a recommended user channel.
Version naming
| Release | Version example |
|---|---|
| Regular final | 2026.9.6 |
| Beta prerelease | 2026.9.6-beta.1 |
| Regular correction | 2026.9.6-1 |
| Extended-stable | 2026.8.33, followed by 2026.8.34 for its next maintenance release |
Versions use year.month.patch, without zero-padding. The patch is a release
number within the month, not a day of the month. Regular releases use patches
below 33; extended-stable starts at 33. Git tags add v, as in v2026.9.6.
Published npm versions and release tags are never replaced. A fix receives a new version. Alpha-only versions do not advance the regular release number.
Release cadence
Releases normally go to beta first and move to stable after validation.
For core and every published official npm plugin, beta must be at least as
new as latest; an already newer beta stays unchanged. A prerelease is older
than the final version with the same base number.
A final version published to the beta channel still has to meet the stable validation requirements below. The npm channel alone does not determine which checks apply.
Release validation
Stable publication requires stable or full validation, longer-running soak tests, and blocking performance checks. These requirements also apply to a final version first published on the beta channel. Beta-profile evidence cannot qualify stable.
Every selected validation lane must pass; publication waivers cannot bypass failures or required coverage. Validation covers source CI, packages, plugins, Gateway installs and upgrades, and selected app, UI, Telegram, QA, and live-provider checks. All-group qualification includes all nine Gateway install/upgrade combinations across Linux, Windows, and macOS. Coverage otherwise varies by profile and selected operating systems. Check the release's recorded coverage: skipped or deferred checks are not passes.
See Full release validation for coverage by profile and how to interpret the results.
Packages and apps can become available at different times
A published Gateway release does not mean every native app is ready. Signing and publishing the apps can finish separately from npm, Docker, and the GitHub release.
Check the release's assets and announcements for each platform. A pending app build or an accepted publication request is not a completed app release. Extended-stable is a Gateway distribution and does not publish native apps.
Release notes and verification
The release notes describe user-facing changes. GitHub releases also carry validation results, dependency reports, and checks of the published packages. These records identify the tested version and the files that shipped. Later documentation updates may improve the release notes without rebuilding or replacing packages.
For dependency review, see Dependency locking. Release dependency archives include npm-format locks separately from the package tarballs.
Downstream packaging
To consume a release lock:
- Download
openclaw-<version>-dependency-evidence.zipfrom the GitHub release. Opendependency-evidence/npm-package-locks.json(schemaVersion: 1) and select thepackagesentry matching the exact packagenameandversion. - Reject entries with a nonempty
omittedWorkspaceDependenciesarray. These are partial locks: the generator omits siblingworkspace:runtime dependencies that publish in the same release. The report counts these entries inpackagesWithOmittedWorkspaceDependencies. - Verify that
dependency-evidence/dependency-evidence-manifest.json'sreleaseSha, the report'ssourceSha, and the OpenClaw commit you pin all match. The report also records the sourcepnpm-lock.yamlSHA-256. - Serialize
entry.lockaspackage-lock.jsonusing two-space JSON indentation and a trailing newline, then verify its SHA-256 againstentry.lockSha256. - Before
npm ci, carry the sourcepnpm-workspace.yamloverrides into the consumingpackage.json, or rewrite nesteddependenciesandoptionalDependenciesspecs to their locked versions. The generated locks encode workspace overrides, so unmodified specs can fail npm's lock-sync check.
The companion npm-package-locks.md includes counts and a package table. Each
entry records bundleRuntimeDependencies and direct dependency counts so
packagers can identify lockless packages that need an external lock.
Maintainer procedures
Release preparation, publishing commands, approvals, and recovery live in the release-maintainer skill. Credential handling and emergency procedures remain in the private maintainer runbook. Former section links below lead to their corresponding procedures.
Extended-stable preparation and publication.
Resumable release orchestration.
Post-release documentation publication.
Runtime generation design proposal (not shipped behavior).
Interrupted preparation and publication.
Regular publication and verification.