Release Process

• Overview
• Platform Targets
• Pre-Release Checklist
• Version Bump Process
• Tag and Release
• Automated Release Pipeline
  • release.yml (cargo-dist)
  • release-plz.yml
• Changelog Generation
• Rollback Procedure
• Prerelease Versions
• Versioning Policy

ruley releases are automated via cargo-dist and GitHub Actions. This chapter documents the release workflow and verification procedures.

Overview

Pushing a version tag (e.g., v1.0.0) triggers the release workflow, which:

1. Validates the tag version matches Cargo.toml
2. Builds binaries for all 5 platform targets
3. Generates SHA256 checksums
4. Signs artifacts via Sigstore/GitHub Attestations
5. Creates a GitHub release with changelog and binaries
6. Publishes to crates.io (non-prereleases only)
7. Updates the Homebrew tap

Configuration lives in dist-workspace.toml.

Platform Targets

Pre-Release Checklist

Before creating a release:

• All tests pass locally: just ci-check
• Zero clippy warnings: cargo clippy --all-targets --all-features -- -D warnings
• Documentation is up to date (README.md, CHANGELOG.md)
• Review open issues and PRs for release blockers
• Release build succeeds: cargo build --release
• Binary works correctly: ./target/release/ruley --help
• Dry-run crates.io publish: cargo publish --dry-run --all-features

Version Bump Process

1. Update the version in Cargo.toml:

   version = "X.Y.Z"
   

2. Run cargo update to update Cargo.lock.

3. Generate the changelog:

   just changelog
   

4. Review and edit CHANGELOG.md for the new version entry.

5. Commit all changes:

   git add Cargo.toml Cargo.lock CHANGELOG.md
   git commit -s -m "chore(release): prepare for vX.Y.Z"
   

Tag and Release

1. Create an annotated tag:

   git tag -a vX.Y.Z -m "Release vX.Y.Z"
   

2. Push the tag to trigger the release workflow:

   git push origin vX.Y.Z
   

Automated Release Pipeline

The release is managed by two GitHub Actions workflows:

release.yml (cargo-dist)

Triggered by v* tags. Builds platform binaries, creates the GitHub release, publishes to crates.io, and updates the Homebrew tap.

release-plz.yml

Runs on every push to main:

• release-plz-pr: Creates a release preparation PR with version bumps and changelog updates
• release-plz-release: Publishes to crates.io when version changes are merged

Changelog Generation

Changelogs are generated by git-cliff using the configuration in cliff.toml. Commits follow the Conventional Commits specification and are grouped by type:

• Features, Bug Fixes, Refactoring, Documentation, Performance, Testing, Miscellaneous, Security

Rollback Procedure

If a release needs to be rolled back:

1. Delete the tag locally: git tag -d vX.Y.Z
2. Delete the tag remotely: git push origin :refs/tags/vX.Y.Z
3. Delete the GitHub release via the web interface
4. Yank from crates.io: cargo yank --version X.Y.Z

Yanking prevents new installs but does not remove the package. Existing Cargo.lock files referencing this version will still work.

Prerelease Versions

For release candidates or beta releases:

• Use a prerelease tag: v1.0.0-rc.1, v1.0.0-beta.1
• The release workflow marks these as prereleases on GitHub
• Prerelease versions are not published to crates.io automatically

Versioning Policy

ruley follows Semantic Versioning:

• Major (X.0.0): Breaking changes to CLI interface or config format
• Minor (0.X.0): New features, new providers, new output formats
• Patch (0.0.X): Bug fixes, dependency updates, documentation