dotfiles/common/claude/skills/rust-crate-release/SKILL.md

name, description

name	description
rust-crate-release	Release and benchmarking procedure for Connor's Rust crates (ordinary-diffeq, astrokit) — the branch/tag/publish sequence, and the criterion baseline method with mainframe's measured noise floor. Use when cutting a release, bumping a version, publishing to crates.io, or measuring whether a change cost performance.

Releasing and benchmarking a Rust crate

The standing rules that apply to every edit — one coherent change at a time, zero warnings, cargo fmt, 0.x breaking changes are minor bumps, a Gitea issue per feature — stay in ~/.claude/CLAUDE.md under "Rust libraries". This file holds the two procedures you only need when you are actually releasing or benchmarking.

Benchmarking, when a change could plausibly cost something

criterion, and measure rather than assert:

• Baseline and change in one sitting: git stash push -- src, cargo bench, git stash pop, cargo bench again. Criterion compares against the baseline it just saved and prints the delta.
• Then run the identical binary once more to see the noise floor. On mainframe that drift is around a percent, larger than most "no regression" claims, so a 0.9% reading means nothing until you know it.
• Never run two cargo invocations at once. They fight over the target lock, starve each other on a loaded box, and the timings come out worthless.
• Write down the measured numbers, not the conclusion drawn from them.

The release process

Once the work itself is committed and pushed:

git checkout -b release/0.6.0
# bump version in Cargo.toml, nothing else
git commit -am "Release 0.6.0"   # body: what changed, and what it breaks
git checkout main && git merge --no-ff release/0.6.0
git tag -a v0.6.0 -m "<crate> 0.6.0 - <one line>"
git push origin main release/0.6.0 v0.6.0
cargo package --list && cargo publish --dry-run && cargo publish

The release commit touches Cargo.toml alone, so the tag is the tree that was tested. cargo package --list is the check that exclude is doing its job and no scratch file is going out. These repos have no Gitea release entries — the annotated tag is the release, and Gitea lists it under Tags. A publish cannot be undone; a bad version can only be yanked.