release

Release Procedure

This document describes the standard release process for agtrace.

How releasing works

The release is split between local steps and CI:

• Local (cargo release): bump versions, update CHANGELOG, commit, tag, push. release.toml sets publish = false, so nothing is published from your machine.
• CI (.github/workflows/release.yml, triggered by the v* tag push):
  • publish-crates: publishes all crates to crates.io in dependency order using the CARGO_REGISTRY_TOKEN repository secret
  • build-local/global-artifacts + host: cargo-dist builds binaries for all platforms and creates the GitHub Release
  • publish-npm: publishes the npm package

Do NOT publish to crates.io locally. No cargo login is needed. If a crate version is already on crates.io when CI runs, cargo publish fails with "already uploaded" and the whole release workflow (including the GitHub Release) is blocked.

Prerequisites

• On main branch with clean working directory
• Tools installed: git-cliff and cargo-release (brew install git-cliff cargo-release or cargo install git-cliff cargo-release)

Release Steps

0. Set Release Level

Choose the release level (patch, minor, or major):

# Set release level
RELEASE_LEVEL=patch  # or: minor, major

1. Dry-run (Verification)

Check what will happen without making changes (dry-run is the default):

cargo release --workspace ${RELEASE_LEVEL}

Confirm the version bump and the "Pushing main, vX.Y.Z to origin" plan.

2. Update CHANGELOG

Generate CHANGELOG entries for changes since the last release:

# Get the latest tag and calculate next version
LAST_TAG=$(git describe --tags --abbrev=0)
CURRENT_VERSION=${LAST_TAG#v}  # Remove 'v' prefix

# Calculate next version based on release level
IFS='.' read -r major minor patch <<< "$CURRENT_VERSION"
case "$RELEASE_LEVEL" in
  major) NEXT_VERSION="$((major + 1)).0.0" ;;
  minor) NEXT_VERSION="${major}.$((minor + 1)).0" ;;
  patch) NEXT_VERSION="${major}.${minor}.$((patch + 1))" ;;
esac

echo "Current version: $CURRENT_VERSION"
echo "Next version: $NEXT_VERSION"

# Generate changelog for commits since last tag with version and date
git cliff ${LAST_TAG}..HEAD --unreleased --tag v${NEXT_VERSION} --prepend CHANGELOG.md