Checklist Release (npm + macOS)

Dùng pnpm (Node 22+) từ thư mục gốc của repo. Giữ working tree sạch trước khi tag/publish nhé.

Operator trigger

Khi operator nói “release”, làm ngay các bước preflight sau (không hỏi thêm trừ khi bị block):

  • Đọc tài liệu này và docs/platforms/mac/release.md.
  • Load env từ ~/.profile và xác nhận SPARKLE_PRIVATE_KEY_FILE + các biến App Store Connect đã được set (SPARKLE_PRIVATE_KEY_FILE nên nằm trong ~/.profile).
  • Dùng Sparkle keys từ ~/Library/CloudStorage/Dropbox/Backup/Sparkle nếu cần.
  1. Version & metadata
  • Tăng version trong package.json (ví dụ: 2026.1.29).
  • Chạy pnpm plugins:sync để đồng bộ version package extension + changelog.
  • Cập nhật CLI/version strings: src/cli/program.ts và Baileys user agent trong src/provider-web.ts.
  • Xác nhận package metadata (name, description, repository, keywords, license) và bin map trỏ đến openclaw.mjs cho openclaw.
  • Nếu dependencies thay đổi, chạy pnpm install để cập nhật pnpm-lock.yaml.
  1. Build & artifacts
  • Nếu A2UI inputs thay đổi, chạy pnpm canvas:a2ui:bundle và commit file src/canvas-host/a2ui/a2ui.bundle.js đã cập nhật.
  • pnpm run build (tạo lại dist/).
  • Kiểm tra npm package files đã bao gồm tất cả thư mục dist/* cần thiết (đặc biệt là dist/node-host/** và dist/acp/** cho headless node + ACP CLI).
  • Xác nhận dist/build-info.json tồn tại và có commit hash đúng (CLI banner dùng cái này cho npm installs).
  • Tùy chọn: npm pack --pack-destination /tmp sau khi build; kiểm tra nội dung tarball và giữ lại để đính kèm vào GitHub release (đừng commit nó).
  1. Changelog & docs
  • Cập nhật CHANGELOG.md với các điểm nổi bật cho người dùng (tạo file nếu chưa có); giữ các entry theo thứ tự giảm dần theo version.
  • Đảm bảo các ví dụ/flags trong README khớp với hành vi CLI hiện tại (đặc biệt là các lệnh hoặc options mới).
  1. Validation
  • pnpm build
  • pnpm check
  • pnpm test (hoặc pnpm test:coverage nếu cần coverage output)
  • pnpm release:check (kiểm tra nội dung npm pack)
  • OPENCLAW_INSTALL_SMOKE_SKIP_NONROOT=1 pnpm test:install:smoke (Docker install smoke test, fast path; bắt buộc trước khi release)
    • Nếu npm release trước đó bị lỗi, set OPENCLAW_INSTALL_SMOKE_PREVIOUS=<last-good-version> hoặc OPENCLAW_INSTALL_SMOKE_SKIP_PREVIOUS=1 cho bước preinstall.
  • (Tùy chọn) Full installer smoke (thêm non-root + CLI coverage): pnpm test:install:smoke
  • (Tùy chọn) Installer E2E (Docker, chạy curl -fsSL https://openclaw.ai/install.sh | bash, onboard, rồi chạy tool calls thật):
    • pnpm test:install:e2e:openai (cần OPENAI_API_KEY)
    • pnpm test:install:e2e:anthropic (cần ANTHROPIC_API_KEY)
    • pnpm test:install:e2e (cần cả hai keys; chạy cả hai providers)
  • (Tùy chọn) Spot-check web gateway nếu thay đổi của bạn ảnh hưởng đến send/receive paths.
  1. macOS app (Sparkle)
  • Build + sign ứng dụng macOS, rồi zip lại để phân phối.
  • Tạo Sparkle appcast (HTML notes qua scripts/make_appcast.sh) và cập nhật appcast.xml.
  • Giữ app zip (và dSYM zip tùy chọn) sẵn sàng để đính kèm vào GitHub release.
  • Làm theo macOS release để biết các lệnh chính xác và env vars cần thiết.
    • APP_BUILD phải là số + tăng dần (không có -beta) để Sparkle so sánh version đúng.
    • Nếu notarizing, dùng keychain profile openclaw-notary được tạo từ App Store Connect API env vars (xem macOS release).
  1. Publish (npm)
  • Xác nhận git status sạch; commit và push nếu cần.
  • npm login (xác minh 2FA) nếu cần.
  • npm publish --access public (dùng --tag beta cho pre-releases).
  • Kiểm tra registry: npm view openclaw version, npm view openclaw dist-tags, và npx -y [email protected] --version (hoặc --help).

Troubleshooting (ghi chú từ release 2.0.0-beta2)

  • npm pack/publish bị treo hoặc tạo tarball khổng lồ: macOS app bundle trong dist/OpenClaw.app (và release zips) bị quét vào package. Fix bằng cách whitelist nội dung publish qua package.json files (include dist subdirs, docs, skills; exclude app bundles). Xác nhận bằng npm pack --dry-run rằng dist/OpenClaw.app không được liệt kê.
  • npm auth web loop cho dist-tags: dùng legacy auth để có OTP prompt:
  • npx verification thất bại với ECOMPROMISED: Lock compromised: thử lại với cache mới:
  • Tag cần repoint sau một fix muộn: force-update và push tag, rồi đảm bảo GitHub release assets vẫn khớp:
    • git tag -f vX.Y.Z && git push -f origin vX.Y.Z
  1. GitHub release + appcast
  • Tag và push: git tag vX.Y.Z && git push origin vX.Y.Z (hoặc git push --tags).
  • Tạo/refresh GitHub release cho vX.Y.Z với title openclaw X.Y.Z (không chỉ tag); body nên bao gồm toàn bộ phần changelog cho version đó (Highlights + Changes + Fixes), inline (không có bare links), và không được lặp lại title trong body.
  • Đính kèm artifacts: npm pack tarball (tùy chọn), OpenClaw-X.Y.Z.zip, và OpenClaw-X.Y.Z.dSYM.zip (nếu được tạo).
  • Commit appcast.xml đã cập nhật và push (Sparkle lấy từ main).
  • Từ một thư mục temp sạch (không có package.json), chạy npx -y [email protected] send --help để xác nhận install/CLI entrypoints hoạt động.
  • Thông báo/chia sẻ release notes.

Plugin publish scope (npm)

Mình chỉ publish các npm plugins đã tồn tại dưới scope @openclaw/*. Các bundled plugins không có trên npm vẫn chỉ ở disk-tree (vẫn được ship trong extensions/**).

Quy trình để lấy danh sách:

  1. npm search @openclaw --json và capture các package names.
  2. So sánh với extensions/*/package.json names.
  3. Chỉ publish phần giao nhau (đã có trên npm).

Danh sách npm plugin hiện tại (cập nhật khi cần):

  • @openclaw/bluebubbles
  • @openclaw/diagnostics-otel
  • @openclaw/discord
  • @openclaw/lobster
  • @openclaw/matrix
  • @openclaw/msteams
  • @openclaw/nextcloud-talk
  • @openclaw/nostr
  • @openclaw/voice-call
  • @openclaw/zalo
  • @openclaw/zalouser

Release notes cũng phải gọi tên các bundled plugins tùy chọn mới mà không được bật mặc định (ví dụ: tlon).