Skip to content

Commit 6a0eecd

Browse files
vincentkocvincentkoc
authored
fix(release): separate code and release SHA validation (#105948)
1 parent a778f89 commit 6a0eecd

24 files changed

Lines changed: 691 additions & 288 deletions

‎.agents/skills/openclaw-changelog-update/SKILL.md‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,10 @@ description: Regenerate OpenClaw release changelog sections from git history bef
66
# OpenClaw Changelog Update
77

88
Use this for release changelog rewrites and GitHub release-note source text.
9-
This is mandatory before every beta, beta rerun, stable release, or stable
10-
rerun. Use it with `release-openclaw-maintainer`; this skill owns changelog
11-
content, ordering, grouping, and attribution discipline.
9+
Run it once after the final Code SHA has green Full Release Validation. Do not
10+
rerun it for same-candidate tooling retries, resumed publication, or promotion.
11+
Use it with `release-openclaw-maintainer`; this skill owns changelog content,
12+
ordering, grouping, and attribution discipline.
1213

1314
## Goal
1415

@@ -25,18 +26,21 @@ every human `Thanks @...` attribution.
2526
the target; a newer but divergent tag is not a valid history boundary. Use
2627
an explicit shipped/main-closeout SHA only when it is also reachable from the
2728
target.
28-
- Target ref: exact branch/SHA being released.
29+
- Target ref: the exact green Code SHA. The changelog commit created from this
30+
input becomes the Release SHA.
2931
- Canonical main ref: current `origin/main`, fetched before verification. Release
3032
notes cite the original merged main PR when the same work is carried by a
3133
backport. A release-branch PR is used only while no forward-port exists on
3234
current main.
3335

3436
## Workflow
3537

36-
1. Start on `main` before branching when possible:
38+
1. Confirm the release branch is at the fully validated Code SHA:
3739
- `git fetch --tags origin`
38-
- `git pull --ff-only`
3940
- confirm clean `git status -sb`
41+
- record `git rev-parse HEAD` as the Code SHA
42+
- record the successful Full Release Validation run id and attempt
43+
- stop if any product/version/backport change is still pending
4044
2. Audit history, including direct commits:
4145
- `git log --first-parent --date=iso-strict --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>`
4246
- `git log --first-parent --grep='(#' --date=short --pretty=format:'%h%x09%ad%x09%s' <base-tag>..<target-ref>`
@@ -241,7 +245,13 @@ every human `Thanks @...` attribution.
241245
- `git diff --check`
242246
- for docs/changelog-only changes, no broad tests are required
243247
- commit with `scripts/committer "docs(changelog): refresh YYYY.M.PATCH notes" CHANGELOG.md`
244-
- push, pull/rebase if needed, then branch/rebase release from latest `main`
248+
- record the new commit as the Release SHA and require
249+
`git diff --name-only <code-sha>..<release-sha>` to print only
250+
`CHANGELOG.md`
251+
- push the release branch without rebasing it onto moving `main`
252+
- dispatch SHA-pinned Full Release Validation for the Release SHA with evidence
253+
reuse enabled. It must select `changelog-only-release-v1`; any other changed
254+
path returns the release to the Code SHA validation loop
245255

246256
## Quota / API Outage Rule
247257

‎.agents/skills/openclaw-testing/SKILL.md‎

Lines changed: 24 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,8 @@ rerun after a focused patch.
288288
### Full Release Validation
289289

290290
`Full Release Validation` (`.github/workflows/full-release-validation.yml`) is
291-
the manual "everything before release" umbrella. It resolves a target ref, then
291+
the manual product-validation umbrella. Run the full child matrix on the
292+
product-complete pre-changelog **Code SHA**. It resolves a target ref, then
292293
dispatches:
293294

294295
- manual `CI` for the full normal CI graph, with Android enabled via
@@ -300,30 +301,23 @@ dispatches:
300301
Telegram release lanes
301302
- optional post-publish Telegram E2E when a package spec is supplied
302303

303-
Run it only when validating an actual release candidate, after broad shared CI
304-
or release orchestration changes, or when explicitly asked:
304+
Run the full matrix only when validating an actual Code SHA, after broad shared
305+
CI or release orchestration changes, or when explicitly asked:
305306

306307
```bash
307-
gh workflow run full-release-validation.yml \
308-
--repo openclaw/openclaw \
309-
--ref main \
310-
-f ref=<branch-or-sha> \
311-
-f provider=openai \
312-
-f mode=both \
313-
-f release_profile=stable
308+
node scripts/full-release-validation-at-sha.mjs \
309+
--sha <code-sha> \
310+
--target-ref release/YYYY.M.PATCH
314311
```
315312

316-
Run the workflow itself from the trusted current ref, normally `--ref main`;
317-
child workflows are dispatched from that same ref even when `ref` points at an
318-
older release branch or tag. Full Release Validation has no separate child
319-
workflow ref input; choose the trusted harness by choosing the workflow run ref.
320-
Use `release_profile=minimum|stable|full` to control live/provider breadth:
321-
`minimum` keeps the fastest OpenAI/core release-critical set, `stable` adds the
322-
stable provider/backend set, and `full` adds the broad advisory provider/media
323-
matrix. Do not make `full` faster by silently dropping suites; optimize setup,
324-
artifact reuse, and sharding instead. The parent verifier job appends a child
325-
overview plus slowest-job tables for child runs; rerun only that verifier after
326-
a child rerun turns green.
313+
The helper pins the trusted workflow revision on current `main` while targeting
314+
the historical release SHA and recording the canonical release branch as
315+
context. It infers `beta` for alpha/beta package versions and `stable` for
316+
stable/correction versions. Pass `-f release_profile=full` only for the broad
317+
advisory provider/media sweep. Do not make `full` faster by silently dropping
318+
suites; optimize setup, artifact reuse, and sharding instead. The parent
319+
verifier job appends a child overview plus slowest-job tables for child runs;
320+
rerun only that verifier after a child rerun turns green.
327321

328322
Standalone manual `CI` dispatches do not run the plugin prerelease suite, the
329323
extension batch sweep, or the release-only `agentic-plugins` Vitest shard. Those
@@ -341,6 +335,15 @@ parent gate. If a child workflow failed but was later rerun successfully, rerun
341335
only the failed parent verifier job; do not dispatch a new full umbrella unless
342336
the release evidence is stale.
343337

338+
Once the Code SHA is green, generate and commit only `CHANGELOG.md`. The new
339+
**Release SHA** is eligible for product-evidence reuse only when GitHub proves
340+
that it is a descendant of the Code SHA and the complete changed path set is
341+
exactly `CHANGELOG.md`. Dispatch the same SHA-pinned helper for the Release SHA;
342+
the resulting parent records `changelog-only-release-v1` and reuses the Code
343+
SHA children. Package, install/update, and release-note proof still runs on the
344+
Release SHA because its tarball bytes changed. Any non-changelog path
345+
invalidates reuse and requires a new Code SHA full matrix.
346+
344347
For bounded recovery after a focused fix, pass `-f rerun_group=<group>`.
345348
Supported umbrella groups are `all`, `ci`, `plugin-prerelease`,
346349
`release-checks`, `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`,

‎.agents/skills/release-openclaw-ci/SKILL.md‎

Lines changed: 39 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ Use this with `$release-openclaw-maintainer` and `$openclaw-testing` when a rele
2424
fails, the parent cancels the remaining child matrix and prints the failed
2525
job summary. Inspect that first red job instead of waiting for unrelated
2626
matrix tails.
27+
- Treat the product-complete pre-changelog commit as the Code SHA. Full product
28+
validation and performance evidence bind to that SHA. The later Release SHA
29+
may reuse those results only when it is a descendant whose complete changed
30+
path set is exactly `CHANGELOG.md`.
2731
- In a sparse worktree or Testbox source sync, first confirm `package.json`,
2832
`pnpm-lock.yaml`, and every source path the selected check reads. If any are
2933
absent, that checkout cannot validate a release dependency or Docker lane:
@@ -68,14 +72,14 @@ non-billable credentials fail before the expensive release matrix.
6872

6973
## Dispatch
7074

71-
Start product performance evidence as early as the release SHA exists, in
75+
Start product performance evidence as early as the Code SHA exists, in
7276
parallel with other release work:
7377

7478
```bash
7579
gh workflow run openclaw-performance.yml \
7680
--repo openclaw/openclaw \
7781
--ref main \
78-
-f target_ref=<release-sha> \
82+
-f target_ref=<code-sha> \
7983
-f profile=release \
8084
-f repeat=3 \
8185
-f deep_profile=false \
@@ -93,7 +97,7 @@ gh workflow run openclaw-performance.yml \
9397
early standalone run is for overlap and faster regression discovery, but a
9498
regression or missing child run blocks the parent validation.
9599

96-
Prefer the trusted workflow on `main`, target the exact release SHA:
100+
Prefer an immutable trusted-main workflow revision, target the exact Code SHA:
97101

98102
- Keep trusted-workflow checks compatible with frozen release targets. If
99103
`main` adds a target-owned guard script or package command after the release
@@ -103,23 +107,30 @@ Prefer the trusted workflow on `main`, target the exact release SHA:
103107
newer `main`-only check.
104108

105109
```bash
106-
gh workflow run full-release-validation.yml \
107-
--repo openclaw/openclaw \
108-
--ref main \
109-
-f ref=<release-sha> \
110-
-f provider=openai \
111-
-f mode=both \
112-
-f release_profile=full \
113-
-f rerun_group=all
110+
node scripts/full-release-validation-at-sha.mjs \
111+
--sha <code-sha> \
112+
--target-ref release/YYYY.M.PATCH
114113
```
115114

116115
For immutable workflow proof on a moving `main`, use
117-
`pnpm ci:full-release --sha <release-sha>`. Its canonical `release-ci/*` ref
118-
keeps exact-target evidence reuse enabled after proving the workflow commit is
119-
still on trusted `main` lineage. Pass `-f reuse_evidence=false` only when the
120-
operator intentionally needs a fresh full run.
121-
122-
Use `release_profile=stable` unless the operator explicitly asks for the broad advisory provider/media matrix. Stable and full profiles force the release soak; the beta profile may opt in with `run_release_soak=true`. Use narrow `rerun_group` after focused fixes.
116+
`pnpm ci:full-release --sha <code-sha> --target-ref
117+
release/YYYY.M.PATCH`. Its canonical `release-ci/*` ref keeps evidence reuse
118+
enabled after proving the workflow commit is still on trusted `main` lineage.
119+
Pass `-f reuse_evidence=false` only when the operator intentionally needs a
120+
fresh full run.
121+
122+
After the Code SHA is green, commit only `CHANGELOG.md` and run the same helper
123+
against the Release SHA. The parent must report
124+
`policy=changelog-only-release-v1`, `evidenceSha=<code-sha>`, and
125+
`changedPaths=["CHANGELOG.md"]`; it should reuse the product matrix instead of
126+
dispatching child lanes. Npm preflight and package/install acceptance still run
127+
against the exact Release SHA and its new tarball bytes.
128+
129+
The SHA-pinned helper infers `beta` for alpha/beta package versions and `stable`
130+
for stable/correction versions. Pass `release_profile=full` only when the
131+
operator explicitly asks for the broad advisory provider/media matrix. Stable
132+
and full profiles force the release soak; the beta profile may opt in with
133+
`run_release_soak=true`. Use narrow `rerun_group` after focused fixes.
123134
Publish with `openclaw-release-publish.yml` using `release_profile=from-validation`
124135
unless a maintainer intentionally wants to cross-check a specific profile; the
125136
publish workflow reads the effective profile from the full-validation manifest.
@@ -154,7 +165,15 @@ Stop watchers before ending the turn or switching strategy.
154165
them in a clean-home CLI probe, never as a substitute for a required
155166
Anthropic API-key lane.
156167
5. For live-cache failures, inspect whether it is missing/invalid key, empty text, provider refusal, timeout, or baseline miss. Do not weaken release gates without clear provider evidence.
157-
6. Fix narrowly, run local/changed proof, commit, push, rerun the smallest matching group.
168+
6. Classify before editing:
169+
- product/code failure: fix the release branch, freeze a new Code SHA, run
170+
focused proof, then obtain green full validation for that new SHA
171+
- workflow/harness/infrastructure/credential failure: fix that owner
172+
separately and rerun the same Code SHA
173+
- changelog/release-note failure: change only `CHANGELOG.md`, keep Code SHA
174+
evidence, and repeat Release SHA proof
175+
- publish child/registry selector failure: keep Release SHA and resume the
176+
failed child; never rebuild an immutable version that already published
158177
7. If a required PR CI run is capacity-stalled with queued jobs and no active
159178
jobs, do not cancel unrelated work or accept a generic manual dispatch.
160179
From the PR head branch, dispatch the explicit exact-SHA fallback:
@@ -173,7 +192,8 @@ target_ref=<full-pr-sha> -f include_android=true -f release_gate=true`.
173192

174193
Record:
175194

176-
- release SHA
195+
- Code SHA and Release SHA
196+
- evidence-reuse policy and complete changed-path set
177197
- full parent run URL
178198
- child run IDs and conclusions: CI, Release Checks, Plugin Prerelease, NPM Telegram, Product Performance
179199
- performance comparison result versus earlier releases when available

0 commit comments

Comments
 (0)