chrysb Release Publish
End-to-end workflow for publishing an AlphaClaw release. Produces release notes in the OpenClaw release format, publishes to npm, creates a GitHub release, closes addressed issues, and drafts a tweet.
Workflow
Phase 1: Gather History
- Identify the previous stable tag (
git tag --sort=-v:refname). - Determine the target version. If on a beta prerelease, the stable version is
the base (e.g.
0.6.0-beta.3→0.6.0). Confirm with the user if unclear. - Collect all commits since the last stable tag:
git log v<prev>..HEAD --oneline --no-merges git log v<prev>..HEAD --no-merges --format="----%nCommit: %h%nSubject: %s%n%b" - Identify external contributors:
git log v<prev>..HEAD --all --format="%an" | sort | uniq -c | sort -rn - Find merged PRs and contributor credits:
git log v<prev>..HEAD --all --merges --format="%s" - Check open issues on the repo that may be addressed:
Cross-reference issue descriptions against the commit log to identify fixes.gh issue list --repo chrysb/alphaclaw --state open
Phase 2: Draft Release Notes
Present a draft to the user before publishing. Use this structure:
## AlphaClaw <version>
### What's New
* **Feature name**: concise description of what it does and why it matters.
### Fixes
* **Short label**: what was broken and how it's fixed. Reference issues
(`Fixes #N`) and PRs (`(#N)`) inline. Credit external contributors
(`Thanks @handle.`).
### Contributors
* @handle
Style rules
- Each bullet starts with a bold short label followed by a colon.
- Describe the what and why, not the implementation details.
- Keep What's New and Fixes user-facing: describe behavior, not code structure (no "decomposed into folder-based components", "co-located hooks", etc.). Omit implementation-only changes from the release notes.
- Use active voice ("add", "fix", "remove"), not past tense.
- Reference GitHub issues with
Fixes #N(auto-closes) or#N(link only). - Reference PRs with
(#N). - Credit external contributors with
Thanks @handle.at the end of the bullet. - List all credited contributors in a Contributors section at the bottom.
- Fold reverted commits into their replacement — don't list revert + re-land.
Deciding what goes where
| Commit type | Section |
|---|---|
| New user-facing capability | What's New |
| Bug fix, regression fix | Fixes |
| Dependency bump (OpenClaw, etc.) | What's New (last bullet) |
| Refactor, test backfill, code split, tooling-only change | Skip |
Version bump commits (0.6.0-beta.N) |
Skip |
| Merge commits | Skip |
Phase 3: Review
Present the full draft to the user and wait for approval or edits before proceeding. Do not publish without explicit confirmation.
Phase 4: Publish
Once approved, execute in order:
- Ensure clean state:
git statusshould show no uncommitted changes. Switch tomainif not already there. - Preflight stable template access: for a stable release, run the Render repository permission and remote checks in Phase 4.5 before changing the AlphaClaw version. Abort if the authenticated user cannot push to Render's template; all deployment templates must remain in sync with the release.
- Run tests:
npm test— abort if any fail. - Verify the OpenClaw dependency: if AlphaClaw depends on a pinned
openclawversion, confirmpackage-lock.jsonand the local install resolve to the same version before publishing.
When the release relies on a specific upstream OpenClaw fix, verify it in the installed package rather than carrying local OpenClaw edits. For example:node -p "require('./package.json').dependencies.openclaw" node -p "require('./package-lock.json').packages['node_modules/openclaw'].version" node -p "require('./node_modules/openclaw/package.json').version"grep -R -n "allowConversationAccess" node_modules/openclaw/dist/zod-schema-* node_modules/openclaw/dist/runtime-schema-* - Bump version:
npm version <version>(creates commit + tag). - Push:
git push && git push --tags. - Publish to npm:
npm publish(publishes tolatesttag). - Create GitHub release:
Use a HEREDOC for the body to preserve formatting.gh release create v<version> --title "AlphaClaw <version>" --notes "<body>"
Phase 4.5: Sync Deployment Templates (mandatory for stable releases)
After every stable npm publish to latest, update all three deployment
templates so Railway, Render, and Apex stay pinned to the same AlphaClaw and
OpenClaw versions (deterministic Docker installs, no drift from @chrysb/alphaclaw
latest).
Repos:
~/Projects/openclaw-railway-template(typicallymainfor production;betaonly when cutting a beta — see release-beta skill; mergemainintobetaafter stable pins when you wantbetato match production pins)~/Projects/openclaw-render-template(typicallymain; this checkout must trackhttps://github.com/render-examples/openclaw-render-template.git)~/Projects/openclaw-apex-template(typicallymain)
For each repo:
- Switch to the intended branch (confirm with the user if unclear).
- Set
@chrysb/alphaclawinpackage.jsonto the released version. Do not addoverridesforopenclawin templates unless you are doing one-off debugging — OpenClaw should resolve transitively from AlphaClaw’s declared dependency (same resulting version across templates unless you intentionally diverge). - Run
npm installto refresh or createpackage-lock.json. - Verify the template install resolved the expected OpenClaw version and includes
any upstream OpenClaw fixes AlphaClaw depends on:
If this fails, stop: the template resolved the wrong OpenClaw package or is missing an upstream fix required by AlphaClaw.node -p "require('./node_modules/@chrysb/alphaclaw/package.json').dependencies.openclaw" node -p "require('./node_modules/openclaw/package.json').version" grep -R -n "allowConversationAccess" node_modules/openclaw/dist/zod-schema-* node_modules/openclaw/dist/runtime-schema-* - Commit and push (include both
package.jsonandpackage-lock.jsonwhen the lockfile exists or was added).
Before updating the Render template, verify that the authenticated GitHub user can push to Render's repository and that the local checkout targets it:
gh api repos/render-examples/openclaw-render-template --jq '.permissions.push'
git -C ~/Projects/openclaw-render-template remote get-url origin
The permission check must return true, and origin must be
https://github.com/render-examples/openclaw-render-template.git (or the SSH
equivalent). If the checkout still targets the former chrysb repository,
update it before syncing:
git -C ~/Projects/openclaw-render-template remote set-url origin https://github.com/render-examples/openclaw-render-template.git
git -C ~/Projects/openclaw-render-template fetch origin
Stop before changing or publishing any template if push access is missing; ask
an administrator of render-examples/openclaw-render-template to grant the
authenticated user write access, then repeat the preflight.
Do not skip Render or Apex: pinning only one template while others stay on
latest causes drift and non-reproducible installs between platforms.
Phase 5: Close Issues
For each issue referenced with Fixes #N in the release notes:
gh issue close <N> --repo chrysb/alphaclaw --comment "Fixed in v<version>."
If an issue is partially addressed or only improved (not fully resolved), leave it open and add a comment instead:
gh issue comment <N> --repo chrysb/alphaclaw --body "Improved in v<version> — <brief description>. Leaving open for remaining work."
Phase 6: Draft Tweet
Draft a tweet following the OpenClaw announcement style:
AlphaClaw <version> 🐺
<emoji> <headline feature or fix — one line>
<emoji> <second highlight>
<emoji> <third highlight>
<emoji> <fourth highlight (optional)>
<witty one-liner or tagline>
Tweet style rules
- Keep under 280 characters.
- Use one emoji per line to set the tone (feature type, not decoration).
- Headline the biggest user-facing change first.
- End with a short memorable line — personality over formality.
- Do not include a link; the user will attach the GitHub release card.
- Offer 2–3 alternative closing lines for the user to choose from.
Emergency / Hotfix Releases
For hotfix versions (e.g. 0.6.1) that fix a critical bug:
- Follow the same workflow but scope the history to the previous released tag.
- The release notes can be shorter — a single Fixes section is fine.
- Skip the tweet unless the fix is noteworthy.
Pre-release / Beta Publishes
For beta iterations during development:
npm version prerelease --preid=beta
git push && git push --tags
npm publish --tag beta
Beta publishes do not need GitHub releases, issue closing, or tweets. They are
used for testing via the openclaw-railway-template beta branch.
After each beta publish, remind the user to update the Railway template's
package.json on the beta branch to pin the exact beta version. If you also
ship betas through Render or Apex, pin those templates the same way on the
branch they use for prereleases.