# Release Playbook
This repository uses branch-based release channels with tag-driven publishing.
## Channel Rules
- `stable`:
- Allowed branches: `main` or `release/*`
- Tag format: `vX.Y.Z`
- `beta`:
- Allowed branch: `next`
- Tag format: `vX.Y.Z-beta.N`
- `alpha`:
- Allowed branch: `canary`
- Tag format: `vX.Y.Z-alpha.N`
The publish workflow also enforces:
- tag version equals `Cargo.toml` version
- tag commit belongs to an allowed branch for that channel
- crates publish in dependency order: `gloves-core`, `gloves-config`, then `gloves`
- `CARGO_REGISTRY_TOKEN` must be a crates.io API token with publish rights for
`gloves-core`, `gloves-config`, and `gloves`
## Release Outputs
For each tag, GitHub Actions `Publish` workflow now produces:
- crates.io publish (`gloves` crate)
- GitHub Release assets:
- `gloves-<version>-x86_64-unknown-linux-gnu.tar.gz`
- `gloves-<version>-x86_64-apple-darwin.tar.gz`
- `gloves-<version>-aarch64-apple-darwin.tar.gz`
- `gloves-<version>-x86_64-pc-windows-msvc.zip`
- `checksums.txt` (SHA-256)
Users can install from prebuilt binaries via:
```bash
The setup script installs both OpenClaw skills by default:
- `gloves-cli-usage`
- `gloves-setup-migrate`
## Preflight (all channels)
```bash
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
bun install --frozen-lockfile
bun run build
bun run test
cargo test --all-features --locked
cargo doc --no-deps
cargo publish --dry-run --locked
```
`cargo publish --dry-run --locked` validates the root crate once its dependency
versions already exist on crates.io. On a fresh release, also dry-run the crates
in publish order:
```bash
cargo publish -p gloves-core --dry-run --locked
cargo package -p gloves-config --list
cargo package -p gloves --list
```
Update release files before tagging:
- `Cargo.toml` version
- `CHANGELOG.md`
- `packages/gloves-client/package.json` version
- `packages/gloves-openclaw/package.json` version
## Stable Release (`main` or `release/*`)
Example version: `1.4.0`
```bash
git checkout main
git pull --ff-only
# edit Cargo.toml version -> 1.4.0
# edit CHANGELOG.md
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore(release): 1.4.0"
git tag v1.4.0
git push origin main
git push origin v1.4.0
```
## Beta Release (`next`)
Example version: `1.5.0-beta.1`
```bash
git checkout next
git pull --ff-only
# edit Cargo.toml version -> 1.5.0-beta.1
# edit CHANGELOG.md
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore(release): 1.5.0-beta.1"
git tag v1.5.0-beta.1
git push origin next
git push origin v1.5.0-beta.1
```
## Alpha Release (`canary`)
Example version: `1.5.0-alpha.1`
```bash
git checkout canary
git pull --ff-only
# edit Cargo.toml version -> 1.5.0-alpha.1
# edit CHANGELOG.md
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore(release): 1.5.0-alpha.1"
git tag v1.5.0-alpha.1
git push origin canary
git push origin v1.5.0-alpha.1
```
## Optional: Stabilize from a Release Branch
```bash
git checkout main
git pull --ff-only
git checkout -b release/1.5
git push -u origin release/1.5
```
Apply fixes on `release/1.5`, then create stable tags (`v1.5.Z`) from that branch.
## Troubleshooting
If the `Publish to crates.io` job fails with `403 Forbidden`, the workflow reached
crates.io with a token that does not have publish permission for one or more
workspace crates. Rotate or replace `CARGO_REGISTRY_TOKEN` with a crates.io token
that can publish `gloves-core`, `gloves-config`, and `gloves`, then rerun the tag
workflow.
GitHub release assets can still succeed when crates.io publishing fails. Treat the
release as incomplete until the crates.io publish job is green.
The crates publish job skips versions that already exist on crates.io so a manual
publish or a rerun against the same tag can complete cleanly.