mirror of
https://github.com/AgentSeal/codeburn.git
synced 2026-08-21 22:44:31 +00:00
4ca2d4824b
vitest's default glob reached the Electron app's specs under app/, which carry their own vitest config and their own jsdom in app/node_modules. From a root install that fails with ERR_MODULE_NOT_FOUND: jsdom, so the command CONTRIBUTING documents and the one RELEASING.md names as the pre-release gate both error out. Move the scoping CI already applies into package.json: test runs tests/ minus the parallelism-sensitive cache-refresh-lock suites, test:locks runs those three serially, test:watch keeps watch mode at the same scope. The first two are byte-identical to the invocations .github/workflows/tests.yml spells out, so the workflow can be pointed at the scripts to stop the two drifting apart again; that edit is left out of this PR so it needs no workflow permissions. test plus test:locks together still cover all 192 files under tests/. Scoping the script changes what a trailing path argument means: vitest ORs positional filters, so 'npm test -- tests/providers/hermes.test.ts' would no longer narrow to that file, it would run the whole suite. Rewrite those to 'npx vitest run <path>' everywhere they appear - four provider guides and the MCP design plan, thirteen lines in all. Also refresh the stale test docs: 42 files/568 tests (now 192 under tests/), the per-directory counts, the line claiming vitest does not run in CI which stopped being true when tests.yml landed, and the provider test-gap list, which still named antigravity and gemini after both gained test files. Record the cache-refresh-lock naming convention in CONTRIBUTING, since the split makes it load-bearing: a lock test that misses the prefix runs under the full worker pool and flakes, and one that matches it but is absent from test:locks never runs at all.
200 lines
7.1 KiB
Markdown
200 lines
7.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
npm test
|
|
npm run test:locks
|
|
```
|
|
|
|
`npm test` covers `tests/`. `npm run test:locks` runs the three parallelism-sensitive
|
|
`cache-refresh-lock` suites serially; CI treats them as reporting-only, so check them by
|
|
hand here.
|
|
|
|
Verify that the build completes without errors:
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
## CLI Release Process
|
|
|
|
### 1. Update the Version
|
|
|
|
Edit `package.json` to bump the version number. Update both the `version` field at the top and the `package-lock.json` lockfile to match (npm handles this automatically):
|
|
|
|
```bash
|
|
npm version <version>
|
|
```
|
|
|
|
For example, `npm version 0.9.8` updates both files and creates a commit.
|
|
|
|
Alternatively, edit `package.json` by hand and run `npm install` to regenerate the lockfile with the new version.
|
|
|
|
### 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:
|
|
|
|
```markdown
|
|
## Unreleased
|
|
|
|
### ...
|
|
|
|
## 0.9.8 - 2026-05-10
|
|
|
|
### Added
|
|
- Feature X
|
|
|
|
### Fixed
|
|
- Bug Y
|
|
```
|
|
|
|
Commit these changes:
|
|
|
|
```bash
|
|
git add CHANGELOG.md package.json package-lock.json
|
|
git commit -m "chore: bump to 0.9.8"
|
|
```
|
|
|
|
### 3. Publish to npm
|
|
|
|
There is no GitHub Actions workflow for the CLI; the maintainer runs `npm publish` from a clean working tree:
|
|
|
|
```bash
|
|
npm publish
|
|
```
|
|
|
|
The `prepublishOnly` script in `package.json` runs `npm run build` first, which bundles the litellm pricing snapshot and then runs `tsup` to emit `dist/cli.js`.
|
|
|
|
If publishing for the first time on a new machine, run `npm login` first.
|
|
|
|
### 4. Tag the Release
|
|
|
|
After npm accepts the publish, tag the commit and push:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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`.
|