Skill: release-rust

Purpose

Create and publish a new release of the Rust project.

Prerequisites

• All CI checks pass on main
• CHANGELOG.md updated
• cargo-dist installed

Steps

0. Verify crate name availability on crates.io (FIRST TIME PUBLISH ONLY)

Before the very first publish, confirm the crate name is not already taken:

# Check via cargo search
cargo search <your-crate-name>

# Or via API (404 = available, 200 = taken)
curl -s https://crates.io/api/v1/crates/<your-crate-name> | python3 -m json.tool | grep '"name"'

# Or open in browser: https://crates.io/crates/<your-crate-name>

See .agents/skills/crates-io-name-check/SKILL.md for full naming guidance and best practices.

Do not proceed with publishing if the name is taken — choose a unique name first.

1. Pre-release checks

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo nextest run --all-features
cargo audit && cargo deny check

2. Bump version in Cargo.toml

cargo update --workspace

3. Commit and tag

git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore: release vX.Y.Z"
git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin main --tags

4. GitHub Release via CI

Pushing a tag triggers .github/workflows/release.yml:

• Release Preflight: Verifies that the tag matches v$(cat VERSION), checks that the release does not already exist, and asserts manifest consistency.
• Release Gates: Runs release-tier quality checks.
• Changelog: Generated using git-cliff as the canonical source of truth for release notes.
• Dist Build: Builds binaries for all targets via cargo-dist with CycloneDX SBOM and cargo-auditable.
• Attestations: Generates signed GitHub build provenance attestations for all release artifacts.
• Creates GitHub Release: Publishes the release with assets.
• Optionally publishes to crates.io.

5. Verifying Release Attestations

Consumers can verify artifact integrity and build provenance using the GitHub CLI:

gh attestation verify <binary-archive-or-file> --owner d-oit

Version Scheme

• MAJOR.MINOR.PATCH (Semantic Versioning)
• Breaking = MAJOR, features = MINOR, fixes = PATCH

Success Criteria

• Tag on GitHub
• Release with binaries created
• CHANGELOG updated
• Crate name verified unique on crates.io (first publish)

Rationalizations

Red Flags

• Pushing a tag without running pre-release checks
• Bumping the version without updating CHANGELOG.md
• Publishing to crates.io without verifying crate name availability

References

• cargo-dist
• Keep a Changelog
• crates.io naming policy

GH CLI Usage

Post-release failure tracking uses gh issue create directly:

# Create a DORA FDRT tracking issue on release failure
gh issue create \
  --title "🚨 Release vX.Y.Z failed post-release health check" \
  --label "hotfix,release-failure" \
  --body-file .github/ISSUE_TEMPLATE/release-failure.md

This is preferred over actions/github-script for single-purpose issue creation.