From 3bd2bbea341ef248ffc9708f49b3d571be397e0e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 2 Apr 2026 19:11:01 +0100 Subject: [PATCH] docs: clarify npm release workflow inputs --- .../openclaw-release-maintainer/SKILL.md | 9 ++--- docs/reference/RELEASING.md | 36 +++++++++++++++++++ 2 files changed, 41 insertions(+), 4 deletions(-) diff --git a/.agents/skills/openclaw-release-maintainer/SKILL.md b/.agents/skills/openclaw-release-maintainer/SKILL.md index 8adedf32b08..283ac936ec7 100644 --- a/.agents/skills/openclaw-release-maintainer/SKILL.md +++ b/.agents/skills/openclaw-release-maintainer/SKILL.md @@ -218,8 +218,9 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts 7. Create and push the git tag. 8. Create or refresh the matching GitHub release. 9. Start `.github/workflows/openclaw-npm-release.yml` with `preflight_only=true` - and wait for it to pass. Save that run id because the real publish requires - it to reuse the prepared npm tarball. + and choose the intended `npm_dist_tag` (`beta` default; `latest` only for + an intentional direct stable publish). Wait for it to pass. Save that run id + because the real publish requires it to reuse the prepared npm tarball. 10. Start `.github/workflows/macos-release.yml` in `openclaw/openclaw` and wait for the public validation-only run to pass. 11. Start @@ -235,8 +236,8 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts Never reuse old preflight results after the commit changes. 14. Start `.github/workflows/openclaw-npm-release.yml` with the same tag for the real publish, choose `npm_dist_tag` (`beta` default, `latest` only when - you intentionally want direct stable publish), and pass the successful npm - `preflight_run_id`. + you intentionally want direct stable publish), keep it the same as the + preflight run, and pass the successful npm `preflight_run_id`. 15. Wait for `npm-release` approval from `@openclaw/openclaw-release-managers`. 16. If the stable release was published to `beta`, start `.github/workflows/openclaw-npm-promote-beta.yml` with the exact stable diff --git a/docs/reference/RELEASING.md b/docs/reference/RELEASING.md index 7ecff52ab2b..c0346829cb2 100644 --- a/docs/reference/RELEASING.md +++ b/docs/reference/RELEASING.md @@ -75,6 +75,42 @@ OpenClaw has three public release lanes: URL, and a `CFBundleVersion` at or above the canonical Sparkle build floor for that release version +## NPM workflow inputs + +`OpenClaw NPM Release` accepts these operator-controlled inputs: + +- `tag`: required release tag such as `v2026.4.2`, `v2026.4.2-1`, or + `v2026.4.2-beta.1` +- `preflight_only`: `true` for validation/build/package only, `false` for the + real publish path +- `preflight_run_id`: required on the real publish path so the workflow reuses + the prepared tarball from the successful preflight run +- `npm_dist_tag`: npm target tag for the publish path; defaults to `beta` + +Rules: + +- Stable and correction tags may publish to either `beta` or `latest` +- Beta prerelease tags may publish only to `beta` +- The real publish path must use the same `npm_dist_tag` used during preflight; + the workflow verifies that metadata before publish continues + +## Stable npm release sequence + +When cutting a stable npm release: + +1. Run `OpenClaw NPM Release` with `preflight_only=true` +2. Choose `npm_dist_tag=beta` for the normal beta-first flow, or `latest` only + when you intentionally want a direct stable publish +3. Save the successful `preflight_run_id` +4. Run `OpenClaw NPM Release` again with `preflight_only=false`, the same + `tag`, the same `npm_dist_tag`, and the saved `preflight_run_id` +5. If the release landed on `beta`, run `OpenClaw NPM Promote Beta` later with + the exact stable version when you want to move that published build to + `latest` + +That keeps the direct publish path and the beta-first promotion path both +documented and operator-visible. + ## Public references - [`.github/workflows/openclaw-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/openclaw-npm-release.yml)