Release Process

Ark uses dist for release automation. Tagging triggers builds for every supported target, GitHub Releases publication, and npm package publishing. The book deploys to GitHub Pages on the same tag.

Configuration

Cargo.toml's [workspace.metadata.dist]:

[workspace.metadata.dist]
cargo-dist-version = "0.30.3"
ci = "github"
allow-dirty = ["ci"]
installers = ["shell", "powershell", "npm"]
npm-package = "ark"
npm-scope = "@anekoique"
pr-run-mode = "skip"
publish-jobs = ["npm"]
targets = [
  "aarch64-apple-darwin",
  "aarch64-unknown-linux-gnu",
  "x86_64-apple-darwin",
  "x86_64-unknown-linux-gnu",
  "x86_64-pc-windows-msvc",
]
install-path = "CARGO_HOME"
install-updater = false

The dist-generated workflow is at .github/workflows/release.yml — don't hand-edit unless you know what you're doing (the workflow is regenerated by dist generate).

Cutting a release

  1. Bump version. Edit [workspace.package].version in Cargo.toml. Both crates inherit from the workspace; you bump once.
  2. Update lockfile. cargo build --workspace (or any cargo command that touches the lockfile).
  3. Commit. git commit -am "chore: bump to vX.Y.Z".
  4. Tag. git tag vX.Y.Z. The leading v matters — the book deploy workflow triggers on v*.
  5. Push. git push && git push --tags.

The push of the tag triggers two GitHub Actions workflows:

  • release.yml (dist) — builds binaries for every target, publishes a GitHub Release with all artifacts attached, publishes the npm package.
  • book.yml — builds docs/book/ with mdBook, deploys to GitHub Pages.

Verifying

After CI completes:

  • The Releases page should list the new tag with shell/powershell/npm installers.
  • npm view @anekoique/ark version should return the new version.
  • https://anekoique.github.io/ark/ should show the new book.
  • npm install -g @anekoique/ark@<version> then ark --version should return the new version.

Versioning policy

Ark follows semver. The visible CLI surface — ark init, ark load, ark unload, ark remove, ark upgrade, ark context — is covered. ark agent is not.

What counts as a breaking change for the visible surface:

  • Removing or renaming a flag.
  • Changing JSON output schema in a non-additive way (rename, type change). Adding fields is fine.
  • Changing the on-disk format of .ark/.installed.json or .ark.db in a way that older versions can't read.
  • Changing the file layout of .ark/, .claude/commands/ark/, .codex/skills/, or .opencode/commands/ark/.

What's not breaking:

  • Adding a new top-level command.
  • Adding a new flag.
  • Changing slash-command body content (templates).
  • Changing the internal ark agent namespace at all.
  • Adding a new platform.

When in doubt, bump major. The cost of an over-eager major bump is small; the cost of breaking users on a minor is large.

Pre-release checklist

Before tagging:

cargo build --workspace
cargo test --workspace
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
mdbook build docs/book                    # confirm book builds clean

Plus the smoke test:

cargo build --release
TMP=$(mktemp -d)
./target/release/ark load --dir "$TMP"
./target/release/ark unload --dir "$TMP"
./target/release/ark load --dir "$TMP"
./target/release/ark remove --dir "$TMP"
rm -rf "$TMP"

After release

  • If you bumped the embedded template version (template files added/removed), tell users to run ark upgrade in their projects. The CLAUDE.md / AGENTS.md managed blocks and the SessionStart hooks are re-applied unconditionally, but template files honor the user-modification protocol — see ark upgrade for the conflict-resolution policy.
  • Watch the Issues page for the first 24 hours. Common reports after a release: install path issues, hook contract changes (Claude / Codex / OpenCode upstream changes), npm install issues on M1.

One-time GitHub Pages setup

The book.yml workflow uses actions/deploy-pages@v4, which requires Pages to be enabled in repo settings:

  1. Go to Settings → Pages.
  2. Set Source to GitHub Actions (not Deploy from a branch).
  3. Save.

This is a one-time manual step. Once enabled, every tag push deploys the book automatically.