release-workflow

name	release-workflow
description	Release/publish the spikard Rust core crate and CLI end-to-end. Load when releasing or publishing spikard — cutting a new version, tagging, running `gh release create`, and installing the released build locally. Covers version set via Taskfile, CHANGELOG roll, the clean-tree precondition, GitHub release, local install, and artifact cleanup.

Spikard Release Workflow

Ground truth: spikard is a Rust workspace (core library + spikard-cli + polyglot bindings). It has no set-version task — the equivalent is task version:set (a version-sync include). Cargo.toml is the single source of truth; version:set syncs it to every binding manifest.

1. Set the version

task version:set -- X.Y.Z        # e.g. task version:set -- 0.7.0-rc.1

version:set takes the version as a -- positional argument (CLI_ARGS). It runs alef sync-versions --set <version> then the full sync (regenerate READMEs, docs, bindings, scaffold, stubs, e2e, and precise cargo update for the core crate across dependent manifests). Bump variants also exist: task version:bump:patch, task version:bump:minor, task version:bump:major. task version:show prints the current version.

Verify:

task version:show
grep -m1 '^version' Cargo.toml

2. Update the CHANGELOG

Move every [Unreleased] bullet in CHANGELOG.md into a new ## [X.Y.Z] - YYYY-MM-DD section (grouped Added / Changed / Fixed / Removed). Re-create an empty [Unreleased]. Never tag an empty section.

3. Clean-tree precondition (hard gate)

Never release a dirty or failing tree.

poly fmt --check .    # formatting clean (task format:check)
poly lint .           # lint clean (task lint)
task test             # Rust core tests pass (rust:test)

Use poly fmt --fix . (or task format) to apply formatting, then re-stage. For a full cross-binding gate before a release, run task test:all (task test + alef test). Optionally validate manifests with task publish:validate (alef publish validate). Fix any failure — do not release past it.

4. Commit, tag, and publish the GitHub release

git add -A
git commit -m "chore(release): X.Y.Z"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main
git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes

Add --prerelease for RC/beta tags. Use --notes-file from the new CHANGELOG section instead of --generate-notes when the changelog entry is richer. A bare git tag is not a release — always run gh release create. Tag-based releases trigger the multi-platform / multi-registry publish workflows.

5. Install the released CLI locally

cargo install --path crates/spikard-cli --force

Installs the spikard CLI binary from the workspace. (If a change is only in the core crate, task build:release builds spikard core; task build:cli builds the CLI binary to target/release/spikard.) Confirm which spikard and spikard --version reflect X.Y.Z.

6. Clean up build artifacts

task clean        # cargo clean + alef clean + rm -rf dist/ .alef/ caches

task clean runs cargo clean (removing target/ to reclaim space) plus alef clean and removes dist/, .alef/, and language caches.

Anti-patterns

• Reaching for a set-version task — spikard uses task version:set -- X.Y.Z.
• Hand-editing version in Cargo.toml or any binding manifest instead of task version:set.
• Releasing a dirty or lint/test-failing tree.
• Tagging without gh release create.
• AI attribution in commit/tag/release text.