codeburn/RELEASING.md

Releasing CodeBurn

This document describes the actual steps a maintainer takes to cut a CLI or macOS menubar release. CLI releases are run by hand with npm publish; macOS menubar releases are automated by .github/workflows/release-menubar.yml when a mac-v* tag is pushed.

The Electron desktop app (app/) has no CI automation yet, but it is released manually under desktop-v<version> tags: build the artifacts on a macOS host (see app/DISTRIBUTION.md) and gh release upload desktop-v<version> … --clobber them onto the release. See app/DISTRIBUTION.md for how to build and distribute it as an ad-hoc-signed, non-notarized macOS build (plus unsigned Windows and Linux builds).

Versioning

CodeBurn uses semantic versioning (major.minor.patch). The CLI and macOS menubar share the same version number for clarity.

Before Every Release

Run the test suite to catch any regressions:

npm test

Verify that the build completes without errors:

npm run build

CLI Release Process

1. Update the Version

Since the core extraction, a release spans THREE coupled version fields plus a pin, and npm run check:workspace-versions fails the build if they drift:

• root package.json version
• packages/cli/package.json version
• packages/core/package.json version
• packages/cli/package.json dependencies["@codeburn/core"] — an EXACT version pin ("0.9.21", never a range), which must equal the core version.

npm version -w codeburn bumps only the CLI and will fail the gate. Instead, edit all four fields by hand to the same version, then regenerate the lockfile:

npm install --package-lock-only --ignore-scripts
npm run check:workspace-versions

2. Update the Changelog

Edit CHANGELOG.md. Move all changes from the "Unreleased" section into a new section with the version number and today's date:

## Unreleased

### ...

## 0.9.8 - 2026-05-10

### Added
- Feature X

### Fixed
- Bug Y

Commit these changes:

git add CHANGELOG.md packages/cli/package.json package-lock.json
git commit -m "chore: bump to 0.9.8"

3. Publish to npm — core FIRST, then the CLI

There is no GitHub Actions workflow for either package; the maintainer publishes from a clean working tree. Order is mandatory: the CLI's dist imports @codeburn/core at runtime under an exact version pin, so publishing the CLI before its core version exists on the registry makes the CLI uninstallable (ETARGET at install time).

npm publish -w @codeburn/core
npm publish -w codeburn

Core's declarations are emitted by tsc -p tsconfig.build.json (tsup emits the JS); the package publishes publicly via its publishConfig. The CLI's prepublishOnly script runs npm run build first, which bundles the litellm pricing snapshot and then runs tsup to emit packages/cli/dist/cli.js.

If publishing for the first time on a new machine, run npm login first. npm's publish step may prompt for browser authentication.

4. Tag the Release

After npm accepts the publish, tag the commit and push:

git tag v0.9.8
git push origin v0.9.8

The tag is for human reference and to anchor the GitHub Release. No workflow runs on v* tags for the CLI today.

5. Verify npm Publication

npm view codeburn version

5b. Bump the Homebrew Tap

The tap at getagentseal/homebrew-codeburn does not update itself — bump it every CLI release or it drifts (issue #716 sat six versions behind):

curl -sLO "https://registry.npmjs.org/codeburn/-/codeburn-<version>.tgz"
shasum -a 256 codeburn-<version>.tgz
# edit Formula/codeburn.rb in the tap: url version + sha256, commit, push

6. Create a GitHub Release

Use the GitHub CLI to create a release with notes from the changelog:

gh release create v0.9.8 --title v0.9.8 --notes "$(sed -n '/^## 0.9.8/,/^## /p' CHANGELOG.md | head -n -1)"

Or use the web interface to draft a release and copy the changelog section into the body.

macOS Menubar Release Process

The macOS menubar is released separately with its own GitHub Release, but shares the same version number as the CLI.

1. Same Version Bump

Follow the same version bumping process as the CLI. Both package.json and CHANGELOG.md reflect the shared version.

2. Tag the macOS Release

After the CLI tag is published, create a separate tag for the menubar:

git tag mac-v0.9.8
git push origin mac-v0.9.8

3. GitHub Actions Builds the Bundle

The .github/workflows/release-menubar.yml workflow automatically detects the mac-v* tag and:

1. Checks out the repo
2. Runs mac/Scripts/package-app.sh v0.9.8
3. Signs the app bundle (ad-hoc signing)
4. Creates a zip file: CodeBurnMenubar-v0.9.8.zip
5. Computes a SHA-256 checksum: CodeBurnMenubar-v0.9.8.zip.sha256
6. Uploads both to a GitHub Release named "Menubar v0.9.8"

The script output on the build machine shows:

✓ Built /path/mac/.build/dist/CodeBurnMenubar-v0.9.8.zip
✓ Checksum /path/mac/.build/dist/CodeBurnMenubar-v0.9.8.zip.sha256
<sha256-hash>  CodeBurnMenubar-v0.9.8.zip

No manual action is needed; the workflow handles everything.

4. Verify the Release

After the workflow completes, the GitHub Release page shows the zip and sha256 files. The installed CLI command codeburn menubar --force fetches the newest mac-v* menubar release that includes both assets, verifies the checksum and bundle identity, and installs it into ~/Applications.

Homebrew Core

CodeBurn is in homebrew-core. After publishing a new CLI version to npm, the homebrew-core formula is updated automatically by Homebrew's bot or can be bumped manually:

brew bump-formula-pr codeburn --url "https://registry.npmjs.org/codeburn/-/codeburn-<VERSION>.tgz"

Users install with brew install codeburn and upgrade with brew upgrade codeburn.

Replacing Assets on an Existing Release

If a release is published with broken assets (e.g., a menubar zip with a build error), re-run the build and upload the fixed assets without creating a new tag.

Use gh release upload with the --clobber flag to overwrite existing files:

# After re-running mac/Scripts/package-app.sh v0.9.8 to regenerate the zip and sha256
gh release upload mac-v0.9.8 mac/.build/dist/CodeBurnMenubar-v0.9.8.zip --clobber
gh release upload mac-v0.9.8 mac/.build/dist/CodeBurnMenubar-v0.9.8.zip.sha256 --clobber

The GitHub Release page will now serve the fixed assets. The menubar installer selects the newest mac-v* release with CodeBurnMenubar-v*.zip plus its checksum, so users who run codeburn menubar --force after the replacement get the fixed version automatically.

Rollback

If a released version has a critical bug, the fastest path is to fix the bug and cut a new patch release (e.g., 0.9.8 -> 0.9.9). Delete the broken tag locally and on GitHub if it has not yet been widely distributed:

git tag -d v0.9.8
git push origin --delete v0.9.8

npm does not allow republishing to the same version. If you must unpublish from npm, use npm unpublish codeburn@0.9.8 --force (requires Owner role), but this is discouraged and all users who installed that version retain it.

For the menubar, tag a new mac-v0.9.9 and let the workflow build and upload it. Users will see the update pill in the menubar settings and upgrade automatically (or manually via codeburn menubar --force).

Summary

The CLI release is manual: bump the version, update CHANGELOG.md, commit, run npm publish, then tag and create a GitHub Release. The macOS menubar release is automated: pushing a mac-v* tag fires .github/workflows/release-menubar.yml, which builds, signs, zips, and publishes the bundle. The homebrew-core formula is updated automatically or via brew bump-formula-pr.