chrysb / release-publish

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

1. Identify the previous stable tag (git tag --sort=-v:refname).

2. 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.

3. 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"
   `

4. Identify external contributors:
   `
   git log v<prev>..HEAD --all --format="%an" | sort | uniq -c | sort -rn
   `

5. Find merged PRs and contributor credits:
   `
   git log v<prev>..HEAD --all --merges --format="%s"
   `

6. Check open issues on the repo that may be addressed:
   `
   gh issue list --repo chrysb/alphaclaw --state open
   `
   Cross-reference issue descriptions against the commit log to identify fixes.

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

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:

1. Ensure clean state: git status should show no uncommitted changes.
   Switch to main if not already there.

2. 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.

3. Run tests: npm test — abort if any fail.

4. Verify the OpenClaw dependency: if AlphaClaw depends on a pinned
   openclaw version, confirm package-lock.json and the local install resolve
   to the same version before publishing.
   `
   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"
   `
   When the release relies on a specific upstream OpenClaw fix, verify it in the
   installed package rather than carrying local OpenClaw edits. For example:
   `
   grep -R -n "allowConversationAccess" nodemodules/openclaw/dist/zod-schema-* nodemodules/openclaw/dist/runtime-schema-*
   `

5. Bump version: npm version <version> (creates commit + tag).
6. Push: git push && git push --tags.
7. Publish to npm: npm publish (publishes to latest tag).

8. Create GitHub release:
   `
   gh release create v<version> --title "AlphaClaw <version>" --notes "<body>"
   `
   Use a HEREDOC for the body to preserve formatting.

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 (typically main for production; beta
  only when cutting a beta — see release-beta skill; merge main into beta
  after stable pins when you want beta to match production pins)

• ~/Projects/openclaw-render-template (typically main; this checkout must
  track https://github.com/render-examples/openclaw-render-template.git)

• ~/Projects/openclaw-apex-template (typically main)

For each repo:

1. Switch to the intended branch (confirm with the user if unclear).

2. Set @chrysb/alphaclaw in package.json to the released version. Do not add
   overrides for openclaw in 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).

3. Run npm install to refresh or create package-lock.json.

4. Verify the template install resolved the expected OpenClaw version and includes
   any upstream OpenClaw fixes AlphaClaw depends on:
   `
   node -p "require('./node_modules/@chrysb/alphaclaw/package.json').dependencies.openclaw"
   node -p "require('./node_modules/openclaw/package.json').version"
   grep -R -n "allowConversationAccess" nodemodules/openclaw/dist/zod-schema-* nodemodules/openclaw/dist/runtime-schema-*
   `
   If this fails, stop: the template resolved the wrong OpenClaw package or is
   missing an upstream fix required by AlphaClaw.

5. Commit and push (include both package.json and package-lock.json when 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:

1. Follow the same workflow but scope the history to the previous released tag.
2. The release notes can be shorter — a single Fixes section is fine.
3. 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.