Chorus Release Process

Step-by-step guide to cut a new release of Chorus.

Prerequisites

• gh CLI is authenticated (gh auth status)
• Working tree is clean (git status)
• You are on the develop branch

Steps

1. Fetch remote and identify the diff since last release

# Fetch remote tags and branches so local refs are up to date
git fetch --tags origin

# Find the previous release tag
git tag -l 'v*' --sort=-version:refname | head -5

# List commits since previous tag on develop
git log --oneline v<PREV>..develop

# Review each commit for CHANGELOG-worthy changes
git show --stat <commit-hash>

2. Draft CHANGELOG and get user approval

Based on the commits identified in Step 1, draft the new CHANGELOG section and present it to the user for review. Use this structure:

## [X.Y.Z] - YYYY-MM-DD

### Added
- **Feature name**: Description of what was added.

### Changed
- **Area**: Description of what changed.

### Fixed
- **Bug name**: Description of what was fixed.

### Plugin
- Plugin version changes if applicable.

---

Rules:

• Only include commits after the previous release tag
• Group by Added / Changed / Fixed / Deprecated / Removed / Plugin
• Omit empty groups
• Each entry should start with a bold label followed by a concise description
• Separate from the previous release section with ---

IMPORTANT: After drafting, show the CHANGELOG content and the proposed version number to the user. Do NOT proceed until the user explicitly approves. The user may request edits to wording, version number, or grouping.

3. Write CHANGELOG.md (on develop)

After user approval, write the approved content into CHANGELOG.md — add the new section at the top, below the # Changelog header and above the previous release section.

4. Bump all three npm package versions (on develop)

# Keep the coordinated release identity in lockstep:
# package.json
# packages/openclaw-plugin/package.json
# packages/chorus-dsh/package.json

# Refresh OpenClaw's standalone lockfile after editing its package version:
cd packages/openclaw-plugin
npm install --package-lock-only --ignore-scripts --no-audit --no-fund
cd ../..

The GitHub Release tag, root Chorus CLI, OpenClaw plugin, and dsh plugin MUST all use the same X.Y.Z. The coordinated publication preflight rejects any name or version drift before an npm registry write.

Follow semver:

• patch (0.1.0 → 0.1.1): bug fixes, minor additions
• minor (0.1.0 → 0.2.0): new features, non-breaking changes
• major (0.1.0 → 1.0.0): breaking changes

5. Commit to develop and open PR to main

# Commit the release prep on develop
git add CHANGELOG.md package.json \
  packages/openclaw-plugin/package.json \
  packages/openclaw-plugin/package-lock.json \
  packages/chorus-dsh/package.json
git commit -m "chore: bump version to vX.Y.Z and update CHANGELOG"
git push origin develop

# Open a PR from develop → main
gh pr create --base main --head develop \
  --title "chore: release vX.Y.Z" \
  --body "Release vX.Y.Z — version bump and CHANGELOG update."

Wait for CI to pass, then merge the PR:

# Merge the PR (use the PR number returned above)
gh pr merge <PR_NUMBER> --merge

6. Create GitHub release with tag (on main)

After the PR is merged into main:

# Fetch the latest main so the tag targets the correct commit
git fetch origin main

gh release create vX.Y.Z \
  --target main \
  --title "vX.Y.Z" \
  --notes "$(cat <<'EOF'
<paste only the new version's CHANGELOG section here, without the ## header>
EOF
)"

Important: The --notes should contain only the new version's content, not the entire CHANGELOG file.

Publishing the GitHub Release triggers .github/workflows/publish-npm.yml. That workflow prepares and validates all three tarballs before publishing, then publishes Chorus CLI → OpenClaw → dsh through npm Trusted Publishing/OIDC. Do not run the legacy interactive publish scripts as an additional release step.

6.1 Trusted Publisher contract and recovery

Each npm package's Trusted Publisher settings must match:

• repository owner/name: the GitHub repository that contains this workflow;
• workflow filename: publish-npm.yml (exact filename);
• Environment: blank when the workflow has no environment, or the exact same Environment name on both npm and the publish job.

The workflow file path is .github/workflows/publish-npm.yml; npm's Trusted Publisher form takes the filename, not the full path. The job runs on a GitHub-hosted runner with id-token: write, does not use NPM_TOKEN or NODE_AUTH_TOKEN, and leaves provenance enabled. Public-repository publishes must expose an SLSA provenance attestation after upload.

If a run partially publishes the fixed sequence, fix the external failure and use Re-run jobs on the same failed GitHub Actions run. Do not create another tag or GitHub Release and do not bump the version. The rerun queries every exact name@version, records existing versions as skipped-already-published, and continues with the first missing package. Registry lookup errors remain fatal; never assume an ambiguous lookup means “not published.”

7. Sync develop with main and verify

# Pull the merge commit back into develop
git checkout develop
git pull origin develop

# Confirm tag exists
git tag -l 'vX.Y.Z'

# Confirm release is visible
gh release view vX.Y.Z

Checklist

• git fetch --tags origin run — local tags are up to date
• git log v<PREV>..develop reviewed — no commits missed
• CHANGELOG draft presented to user and approved
• CHANGELOG.md written with approved content
• Root, OpenClaw, and dsh package versions are the same X.Y.Z
• OpenClaw package-lock.json refreshed for X.Y.Z
• Changes committed and pushed to develop
• PR from develop → main created, CI passed, and merged
• gh release create with tag targeting main
• publish-npm.yml run passed for all three packages (published or safely skipped)
• Public-package provenance attestations were verified by the workflow
• Release notes contain only the new version's section
• develop synced with main after merge
• gh release view confirms everything looks correct