Release Checklist (npm)
Usepnpm (Node 24+) from the repo root. Keep the working tree clean before tagging/publishing.
Native app releases (macOS, iOS, Android) are cut from the
WednesdayAI-apps repository; this checklist
covers the core npm package only.
Operator trigger
When the operator says “release”, immediately do this preflight (no extra questions unless blocked):- Read this doc. For the macOS app, use the
wednesdayai-mac-releaseskill in WednesdayAI-apps.
- Version & metadata
package.json is the single source of truth and release-please
owns the bump. Derived version files are synchronized by pnpm version:sync in CI and by the
release workflow.
Version hold: release-please-config.json sets "versioning": "always-bump-patch", so every release
stays in the 0.6.x line (0.6.1, 0.6.2, …) whatever the commit types, until the context, memory,
plugin, and optimisation work lands. To leave the hold, delete that key; the next release then bumps
normally (breaking or feat changes move to 0.7.0).
-
Confirm the release-please PR contains the intended
package.jsonversion bump. -
Confirm the release-please sync commit ran
pnpm version:syncand updated derived version files. - Confirm extension package versions match the root version when they are part of the workspace release.
-
Do not edit
docs/install/updating.mdfor a pinned npm version; it intentionally installswednesdayai@latest. -
Native apps version with the core version they sync (
CORE_VERSIONin WednesdayAI-apps); no app stamping happens in this repository (ADR 0101). -
Confirm package metadata: root package name is
wednesdayai(currently0.4.11),binexposes bothwednesdayaiand the compatibilityopenclawcommand, and WhatsApp package name is@wednesdayai/whatsapp. -
Stable publication runs only from
.github/workflows/npm-publish.ymlusing thenpm-publishGitHub environment (OIDC trusted publishing; npm staged publishes for stable). The one sanctioned local path is dev-only:pnpm release:local-install --publish-devpublishes a core and@wednesdayai/whatsapppair built from one commit under thedevdist-tag when Actions is unavailable (ADR 2523). -
If dependencies changed, run
pnpm installsopnpm-lock.yamlis current.
- Build & artifacts
-
If A2UI inputs changed, run
pnpm canvas:a2ui:bundleand commit any updatedsrc/canvas-host/a2ui/a2ui.bundle.js. -
pnpm run build(regeneratesdist/). -
Verify npm package
filesincludes all requireddist/*folders (notablydist/node-host/**anddist/acp/**for headless node + ACP CLI). -
Confirm the packed tarball ships no
docs/content outsidedocs/reference/templates/(full user/admin/developer docs live atdocs.wednesdayai.devand on GitHub, not in the install).docs/reference/templates/BOOT.mdis a docs-only template and is excluded too. When validating sealed package inventories, pass both--sealed-inventoryinputs topnpm release:check.scripts/release-check.tsthen applies each package’s allow/deny policy fromscripts/release-pack-policy.ts, which rejects:- any path outside that package’s allowlist;
- any other
docs/path; - generated
.i18n/output; *.test.*files;- nested
node_modules/paths.
docs/reference/templates/AGENTS.mdandBOOTSTRAP.md. A plainpnpm release:checkdoes not inspect a packed tarball. Separately,pnpm testrunsnpm pack --dry-run --ignore-scriptsfor both packages (scripts/release-pack-contents.test.ts) and checks the listed files against the same policy. That dry run builds no tarball and skipsprepack, so it does not replace sealed-inventory validation. -
Confirm
dist/build-info.jsonexists and includes the expectedcommithash (CLI banner uses this for npm installs), and thatextensions/whatsapp/dist/build-info.jsoncarries the same commit (the publish rails assert it withscripts/release-lockstep-build-info.ts). -
Optional:
npm pack --pack-destination /tmpafter the build; inspect the tarball contents and keep it handy for the GitHub release (do not commit it).
- Changelog & docs
- Do not hand-edit root
CHANGELOG.md; release-please generates it from Conventional Commits. - Add or update a dated
dev-docs/logs/YYYY-MM-DD-*.mdentry for the engineering record when the release contains feature work. - Update
dev-docs/CHANGELOG.mdonly as the narrative index to that dev log. - Ensure README examples/flags match current CLI behavior (notably new commands or options).
- Validation
-
pnpm build -
pnpm check -
pnpm test(orpnpm test:coverageif you need coverage output) -
pnpm release:check(static only: package identity, plugin versions, plugin-sdk exports, and thatpackage.jsonfilesshipsscripts/install.shandscripts/install.ps1, which servehttps://wednesdayai.dev/install.sh. It does not runnpm pack. Use two--sealed-inventory <path>arguments only when validating a sealed candidate.) -
OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke(Docker install smoke test, fast path; required before release)- If the immediate previous npm release is known broken, set
OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version>orOPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1for the preinstall step.
- If the immediate previous npm release is known broken, set
- (Optional) Full installer smoke (adds non-root coverage):
pnpm test:install:smoke - After npm
latestis promoted: runpnpm test:install:hosted; it must confirmhttps://wednesdayai.dev/install.shmatchesscripts/install.shinwednesdayai@latest. - (Optional) Installer E2E (Docker, runs the WednesdayAI install script, onboards, then runs real tool calls):
pnpm test:install:e2e:openai(requiresOPENAI_API_KEY)pnpm test:install:e2e:anthropic(requiresANTHROPIC_API_KEY)pnpm test:install:e2e(requires both keys; runs both providers)
- (Optional) Spot-check the web gateway if your changes affect send/receive paths.
- Publish (npm)
.github/workflows/npm-publish.yml (trusted publishing through the npm-publish GitHub environment; npm ≥ 11.15.0 staged publishing for stable).
- On release creation, the
dispatch-stable-stagejob inrelease-please.ymlautomatically dispatches npm-publish stable staging withrelease_tagandsource_sharesolved from the final tag SHA (release-please may heal derived versions and move the tag before this runs). No human dispatch is needed for the normal flow. - Run
pnpm release:approve vX.Y.Z. It resolves the tag’s commit onorigin, skips packages already live, finds the one stage per remaining package withnpm stage list --json, asks for confirmation, then runsnpm stage approve <stage-id>for@wednesdayai/whatsappand thenwednesdayaion your terminal, where npm asks for 2FA. It then dispatches verification (npm-publish.ymlwithverify_approved=yes), watches the run, and prints the registry state. It stops without approving anything when a package is neither live nor staged, or has more than one stage. Add--dry-runto print the plan only. This approval gate stays human. - Verification checks both packages, including any skipped package, against the recorded pack integrities and installed pair. To run the steps by hand:
npm stage list,npm stage approve <stage-id>per created stage, thengh workflow run npm-publish.yml --ref main -f release_tag=vX.Y.Z -f source_sha=<40-hex tag sha> -f verify_approved=yes. - Verify the registry:
npm view wednesdayai version,npm view wednesdayai dist-tags,npm view @wednesdayai/whatsapp version,npm view @wednesdayai/whatsapp dist-tags, andnpx -y wednesdayai@X.Y.Z --version(or--help). - The scheduled
npm-paritywatchdog backstops this list: it opens or updates a tracking issue when a release tag has no registry counterpart or the dev rail stalls. Treat its issue as release debt, not noise.
@wednesdayai/whatsapp and then wednesdayai with npm stage publish in the same stable job (a package already live at that version is skipped), then stops for maintainer approval of any created stages. Dev publication publishes WhatsApp, then core, directly to the dev dist-tag. Registry mutations name an exact sealed tarball — automation never publishes a working directory and never administers stages or dist-tags through OIDC.
Missed release (tag exists, registry does not)
If a release tag was created but the stable publish never landed (for examplev0.4.11 after the old token-auth EOTP failure), retro-publish from the tag once the identity preconditions hold (source_sha is the full tag commit SHA, the GitHub Release targetCommitish equals that SHA, both package.json and extensions/whatsapp/package.json at that commit have the version in the tag name, and the tag is an ancestor of main):
Troubleshooting
- npm pack/publish hangs or produces huge tarball: the macOS app bundle in
dist/OpenClaw.app(and release zips) get swept into the package. Fix by whitelisting publish contents viapackage.jsonfiles(include dist subdirs,docs/reference/templates, skills; exclude app bundles and any otherdocs/path). Confirm withnpm pack --dry-runthatdist/OpenClaw.appis not listed. - npm auth web loop for dist-tags: use legacy auth to get an OTP prompt:
NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add wednesdayai@X.Y.Z latestNPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add @wednesdayai/whatsapp@X.Y.Z latest
npxverification fails withECOMPROMISED: Lock compromised: retry with a fresh cache:NPM_CONFIG_CACHE=/tmp/npm-cache-$(date +%s) npx -y wednesdayai@X.Y.Z --version
- Tag must not be moved after a late fix: release tags are immutable. Cut a new patch version instead of running
git tag -f.
- GitHub release
- Release-please owns tag creation and push for normal releases. Manual
git tag vX.Y.Z && git push origin vX.Y.Z(orgit push --tags) is only for exceptional flows — release tags are immutable once published (see Troubleshooting). - Create/refresh the GitHub release for
vX.Y.Zwith titleopenclaw X.Y.Z(not just the tag); body should include the full changelog section for that version (Highlights + Changes + Fixes), inline (no bare links), and must not repeat the title inside the body. - Attach artifacts:
npm packtarball (optional). Native app artifacts ship from the WednesdayAI-apps release flow. - From a clean temp directory (no
package.json), runnpx -y wednesdayai@X.Y.Z send --helpto confirm install/CLI entrypoints work. - Announce/share release notes.
- Cut the docs release:
scripts/docs-sync.sh --release vX.Y.Zfrom the repo root. It snapshots the previous minor (keeping four minors in total), opens thedocs: WednesdayAI vX.Y.ZPR against WednesdayAI-docs, and merges it only once the GitHub release is published (not draft). Rerun the same command after publishing; while Actions is billing-blocked, run the script locally. Never merge docs PRs by hand. - Check docs.wednesdayai.dev: the version dropdown shows vX.Y.Z as the default (Latest) alongside
nextand the pinned older minors, and the banner names vX.Y.Z with a working release-notes link.
Trusted npm publishing
Stable publication runs only from.github/workflows/npm-publish.yml through the npm-publish GitHub environment (OIDC trusted publishing; npm staged publishes for stable). Step 5 above is the operator flow; the dev-only local exception is pnpm release:local-install --publish-dev (ADR 2523). For the architecture and the vendoring recipe, see Trusted npm publishing for contributors.
Version locations
package.json version is the single source of truth. Only the release-please Release PR bumps it; never hand-edit it (pnpm version:guard, part of pnpm check, rejects hand edits). All other locations are derived by pnpm version:sync; never edit them directly:
packages/clawdbot/package.jsonandpackages/moltbot/package.json(shimversion)- every
extensions/*/package.jsonversionfield
apps/shared/contracts/CORE_VERSION
and stamps its own app files during contracts:sync (ADR 0101). See
WednesdayAI-apps.
Notes:
docs/install/updating.mdis not derived. It installs@latestand pins no version.
Changelog ownership
The releaseCHANGELOG.md is generated by release-please from Conventional Commits. Do not hand-edit it (ADR 0005). Record narrative history in a dated dev log under dev-docs/logs/ and add a pointer to dev-docs/CHANGELOG.md, the narrative index. Build provenance (version, channel, commit, fork base) lives in dist/build-info.json; the bare wednesdayai --version stays a single SemVer line.
Deprecation policy
Config keys, CLI flags, and SDK exports are never removed immediately when renamed or replaced. Ship a deprecated alias for at least one release cycle, then remove it in a later release with an explicit announcement. For kernel contracts, CI enforces this throughpnpm lint:contracts:surface, which fails a removal that never shipped a @deprecated alias (see Versioned kernel contracts).
- A rename plus alias is backward-compatible, so use a
feat:orfix:commit, notBREAKING CHANGE. - Reserve
BREAKING CHANGEor!for hard removals and incompatibilities with no migration path. - The
openclawtowednesdayairename is the canonical example. The old names stay readable as legacy aliases, so each rename step is not a breaking change. Removing an alias follows the staged plan in ADR 2057 (dev-docs/adr/2057-openclaw-legacy-with-removal.md): primary flip, then a deprecation notice, then removal under its own ADR.
Plugin publish scope (npm)
All bundled extension packages live in the@wednesdayai npm organization:
@wednesdayai/*— every bundled extension is named@wednesdayai/<plugin-id>(ADR 2057).@openclaw/*— belongs to upstream openclaw. Never publish under that scope and never install from it: an@openclaw/<id>install spec for a bundled plugin resolves to the bundled copy shipped with WednesdayAI, not to upstream’s npm package.
private and stay disk-tree only (still
shipped in extensions/**). Today only wednesdayai (the CLI/core) and
@wednesdayai/whatsapp are published on the npm rail.
Process to derive future publish candidates:
- Start from plugin ids under
extensions/*. - Compare with
extensions/*/package.jsonnames (@wednesdayai/<plugin-id>). - Publish new WednesdayAI-native packages under
@wednesdayai/<plugin-id>only after the package has built JavaScript entries and runtime dependency validation. - Keep unpublished packages
"private": true; flipping one to published needs its own ADR-level decision (ADR 0037).
tlon).