Skip to main content

Release Checklist (npm)

Use pnpm (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-release skill in WednesdayAI-apps.
  1. Version & metadata
Do not hand-edit release versions. 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.json version bump.
  • Confirm the release-please sync commit ran pnpm version:sync and 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.md for a pinned npm version; it intentionally installs wednesdayai@latest.
  • Native apps version with the core version they sync (CORE_VERSION in WednesdayAI-apps); no app stamping happens in this repository (ADR 0101).
  • Confirm package metadata: root package name is wednesdayai (currently 0.4.11), bin exposes both wednesdayai and the compatibility openclaw command, and WhatsApp package name is @wednesdayai/whatsapp.
  • Stable publication runs only from .github/workflows/npm-publish.yml using the npm-publish GitHub environment (OIDC trusted publishing; npm staged publishes for stable). The one sanctioned local path is dev-only: pnpm release:local-install --publish-dev publishes a core and @wednesdayai/whatsapp pair built from one commit under the dev dist-tag when Actions is unavailable (ADR 2523).
  • If dependencies changed, run pnpm install so pnpm-lock.yaml is current.
  1. Build & artifacts
  • If A2UI inputs changed, run pnpm canvas:a2ui:bundle and commit any updated src/canvas-host/a2ui/a2ui.bundle.js.
  • pnpm run build (regenerates dist/).
  • Verify npm package files includes all required dist/* folders (notably dist/node-host/** and dist/acp/** for headless node + ACP CLI).
  • Confirm the packed tarball ships no docs/ content outside docs/reference/templates/ (full user/admin/developer docs live at docs.wednesdayai.dev and on GitHub, not in the install). docs/reference/templates/BOOT.md is a docs-only template and is excluded too. When validating sealed package inventories, pass both --sealed-inventory inputs to pnpm release:check. scripts/release-check.ts then applies each package’s allow/deny policy from scripts/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.
    It also requires docs/reference/templates/AGENTS.md and BOOTSTRAP.md. A plain pnpm release:check does not inspect a packed tarball. Separately, pnpm test runs npm pack --dry-run --ignore-scripts for both packages (scripts/release-pack-contents.test.ts) and checks the listed files against the same policy. That dry run builds no tarball and skips prepack, so it does not replace sealed-inventory validation.
  • Confirm dist/build-info.json exists and includes the expected commit hash (CLI banner uses this for npm installs), and that extensions/whatsapp/dist/build-info.json carries the same commit (the publish rails assert it with scripts/release-lockstep-build-info.ts).
  • Optional: npm pack --pack-destination /tmp after the build; inspect the tarball contents and keep it handy for the GitHub release (do not commit it).
  1. 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-*.md entry for the engineering record when the release contains feature work.
  • Update dev-docs/CHANGELOG.md only as the narrative index to that dev log.
  • Ensure README examples/flags match current CLI behavior (notably new commands or options).
  1. Validation
  • pnpm build
  • pnpm check
  • pnpm test (or pnpm test:coverage if you need coverage output)
  • pnpm release:check (static only: package identity, plugin versions, plugin-sdk exports, and that package.json files ships scripts/install.sh and scripts/install.ps1, which serve https://wednesdayai.dev/install.sh. It does not run npm 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> or OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1 for the preinstall step.
  • (Optional) Full installer smoke (adds non-root coverage): pnpm test:install:smoke
  • After npm latest is promoted: run pnpm test:install:hosted; it must confirm https://wednesdayai.dev/install.sh matches scripts/install.sh in wednesdayai@latest.
  • (Optional) Installer E2E (Docker, runs the WednesdayAI install script, onboards, then runs real tool calls):
    • pnpm test:install:e2e:openai (requires OPENAI_API_KEY)
    • pnpm test:install:e2e:anthropic (requires ANTHROPIC_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.
  1. Publish (npm)
The npm rail is .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-stage job in release-please.yml automatically dispatches npm-publish stable staging with release_tag and source_sha resolved 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 on origin, skips packages already live, finds the one stage per remaining package with npm stage list --json, asks for confirmation, then runs npm stage approve <stage-id> for @wednesdayai/whatsapp and then wednesdayai on your terminal, where npm asks for 2FA. It then dispatches verification (npm-publish.yml with verify_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-run to 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, then gh 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, and npx -y wednesdayai@X.Y.Z --version (or --help).
  • The scheduled npm-parity watchdog 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.
Stable publication stages @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 example v0.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):
This restores tag↔registry parity so downstream lockfiles can pin the release immutably. It is not a substitute for the vendoring recipe when the deployed artifact came from a branch build — see Deployment artifact parity and vendoring.

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 via package.json files (include dist subdirs, docs/reference/templates, skills; exclude app bundles and any other docs/ path). Confirm with npm pack --dry-run that dist/OpenClaw.app is 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 latest
    • NPM_CONFIG_AUTH_TYPE=legacy npm dist-tag add @wednesdayai/whatsapp@X.Y.Z latest
  • npx verification fails with ECOMPROMISED: 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.
  1. GitHub release
  • Release-please owns tag creation and push for normal releases. Manual git tag vX.Y.Z && git push origin vX.Y.Z (or git push --tags) is only for exceptional flows — release tags are immutable once published (see Troubleshooting).
  • Create/refresh the GitHub release for vX.Y.Z with title openclaw 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 pack tarball (optional). Native app artifacts ship from the WednesdayAI-apps release flow.
  • From a clean temp directory (no package.json), run npx -y wednesdayai@X.Y.Z send --help to confirm install/CLI entrypoints work.
  • Announce/share release notes.
  • Cut the docs release: scripts/docs-sync.sh --release vX.Y.Z from the repo root. It snapshots the previous minor (keeping four minors in total), opens the docs: WednesdayAI vX.Y.Z PR 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 next and 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.json and packages/moltbot/package.json (shim version)
  • every extensions/*/package.json version field
Native apps (macOS, iOS, Android, and the Swabble wake-word daemon) are not stamped here. They version with the core version they sync: WednesdayAI-apps pins apps/shared/contracts/CORE_VERSION and stamps its own app files during contracts:sync (ADR 0101). See WednesdayAI-apps. Notes:
  • docs/install/updating.md is not derived. It installs @latest and pins no version.

Changelog ownership

The release CHANGELOG.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 through pnpm 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: or fix: commit, not BREAKING CHANGE.
  • Reserve BREAKING CHANGE or ! for hard removals and incompatibilities with no migration path.
  • The openclaw to wednesdayai rename 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.
Bundled plugins that are not on npm are 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:
  1. Start from plugin ids under extensions/*.
  2. Compare with extensions/*/package.json names (@wednesdayai/<plugin-id>).
  3. Publish new WednesdayAI-native packages under @wednesdayai/<plugin-id> only after the package has built JavaScript entries and runtime dependency validation.
  4. Keep unpublished packages "private": true; flipping one to published needs its own ADR-level decision (ADR 0037).
Release notes must also call out new optional bundled plugins that are not on by default (example: tlon).