Raibid Labs Documentation

RELEASE

3 min read

Release Process

This document describes how to publish new versions of the Scarab Navigation Protocol crates to crates.io.

Prerequisites

  1. You must have publish permissions for both crates on crates.io
  2. You need a crates.io API token stored as CARGO_REGISTRY_TOKEN in GitHub Secrets
  3. All tests must pass on the main branch
  4. The working directory should be clean (no uncommitted changes)

Publishing Strategy

This repository contains two crates:

  • scarab-nav-protocol: The core protocol definitions
  • scarab-nav-client: The client library (depends on protocol)

You can publish them independently or together.

When publishing both crates with the same version:

  1. Update version in both Cargo.toml files:

    # Edit crates/scarab-nav-protocol/Cargo.toml
# Edit crates/scarab-nav-client/Cargo.toml
# Update version in scarab-nav-client's dependency on scarab-nav-protocol

  2. Commit the version changes:

    git add .
git commit -m "chore: bump version to 0.2.0"
git push origin main

  3. Create and push a version tag:

    git tag v0.2.0
git push origin v0.2.0

  4. The GitHub Actions workflow will:

    • Run all tests
    • Publish scarab-nav-protocol first
    • Wait 30 seconds for it to be available
    • Publish scarab-nav-client
    • Create a GitHub Release

Option 2: Publishing Protocol Only

If you only need to update the protocol:

  1. Update version in crates/scarab-nav-protocol/Cargo.toml

  2. Commit and push:

    git add crates/scarab-nav-protocol/Cargo.toml
git commit -m "chore(protocol): bump version to 0.2.0"
git push origin main

  3. Create and push a protocol-specific tag:

    git tag scarab-nav-protocol-v0.2.0
git push origin scarab-nav-protocol-v0.2.0

Option 3: Publishing Client Only

If you only need to update the client:

  1. Update version in crates/scarab-nav-client/Cargo.toml

  2. If the client needs a newer protocol version, update the dependency version too

  3. Commit and push:

    git add crates/scarab-nav-client/Cargo.toml
git commit -m "chore(client): bump version to 0.2.0"
git push origin main

  4. Create and push a client-specific tag:

    git tag scarab-nav-client-v0.2.0
git push origin scarab-nav-client-v0.2.0

Tag Format

The release workflow recognizes these tag formats:

  • v*.*.* - Publishes both crates (e.g., v0.2.0)
  • scarab-nav-protocol-v*.*.* - Publishes protocol only (e.g., scarab-nav-protocol-v0.2.0)
  • scarab-nav-client-v*.*.* - Publishes client only (e.g., scarab-nav-client-v0.2.0)

Pre-release Versions

For alpha, beta, or release candidate versions:

  1. Use semantic versioning with pre-release identifiers:

    • v0.2.0-alpha.1
    • v0.2.0-beta.1
    • v0.2.0-rc.1

  2. The GitHub Release will be marked as a pre-release automatically

Manual Publishing (Fallback)

If you need to publish manually:

# Publish protocol first
cd crates/scarab-nav-protocol
cargo publish
 
# Wait for it to be available on crates.io (usually 1-2 minutes)
 
# Then publish client
cd ../scarab-nav-client
cargo publish

Troubleshooting

”Version already exists” error

If a version was already published, you must bump the version number. You cannot republish the same version.

Client fails to find protocol version

If publishing both crates and the client fails because it can’t find the protocol version:

  1. The protocol might not be available yet on crates.io
  2. Wait a few minutes and retry
  3. Or publish them separately with a delay

Verification failed

If the workflow fails verification:

  1. Ensure the tag version matches the Cargo.toml version exactly
  2. Check that all tests pass locally: cargo test --all-features --workspace
  3. Check formatting: cargo fmt --all -- --check
  4. Check clippy: cargo clippy --all-features --workspace -- -D warnings

Post-Release Checklist

After a successful release:

  • Verify the crates appear on crates.io
  • Check that docs.rs built documentation successfully
  • Update any dependent projects
  • Announce the release if it’s a major version

Yanking a Release

If you need to yank a broken release:

cargo yank --vers 0.2.0 scarab-nav-protocol
cargo yank --vers 0.2.0 scarab-nav-client

This removes it from being downloaded by new projects but doesn’t break existing users.

Graph View