PUBLISHING

Publishing to crates.io

Quick Start

First Time Setup

1. Get a crates.io API token

   • Go to https://crates.io/me
   • Generate a new API token
   • Add it to GitHub Secrets as CARGO_REGISTRY_TOKEN

2. Verify you have publish permissions

   • You need to be an owner of both crates on crates.io
   • For first publish, this happens automatically when you publish

Publishing a New Version

The easiest way is to use the release helper script:

# For a new version of both crates
./scripts/release.sh 0.2.0 both
 
# For protocol only
./scripts/release.sh 0.2.0 protocol
 
# For client only
./scripts/release.sh 0.2.0 client

The script will:

1. Update version numbers in Cargo.toml files
2. Run tests, clippy, and formatting checks
3. Verify the package can be published
4. Give you instructions for the git commands

Then follow the instructions to commit, push, and tag the release.

Manual Process

If you prefer to do it manually:

1. Update version numbers

   # Edit version in Cargo.toml files
   vim crates/scarab-nav-protocol/Cargo.toml
   vim crates/scarab-nav-client/Cargo.toml

2. Run checks

   cargo test --all-features --workspace
   cargo clippy --all-features --workspace -- -D warnings
   cargo fmt --all -- --check

3. Verify package

   cd crates/scarab-nav-protocol
   cargo publish --dry-run --allow-dirty

4. Commit and tag

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

GitHub Actions Workflow

The release workflow automatically:

1. Triggers on tag push: Any tag matching v*.*.*, scarab-nav-protocol-v*.*.*, or scarab-nav-client-v*.*.*

2. Runs tests: Full test suite on Ubuntu

3. Publishes to crates.io:

   • For v*.*.* tags: Publishes both crates (protocol first, then client after 30s delay)
   • For scarab-nav-protocol-v*.*.*: Publishes protocol only
   • For scarab-nav-client-v*.*.*: Publishes client only

4. Creates GitHub Release: Automatically generates release notes

Tag Format Reference

Tag Format	What Gets Published	Example
v*.*.*	Both crates with same version	v0.2.0
scarab-nav-protocol-v*.*.*	Protocol only	scarab-nav-protocol-v0.2.0
scarab-nav-client-v*.*.*	Client only	scarab-nav-client-v0.2.1

Verification

After pushing a tag, you can monitor the release:

1. GitHub Actions: https://github.com/raibid-labs/scarab-nav-protocol/actions
2. crates.io:
   • https://crates.io/crates/scarab-nav-protocol
   • https://crates.io/crates/scarab-nav-client
3. docs.rs:
   • https://docs.rs/scarab-nav-protocol
   • https://docs.rs/scarab-nav-client

Troubleshooting

”Not allowed to upload to crates.io”

You need to be added as an owner. For first publish, this isn’t needed. For subsequent publishes, an existing owner needs to run:

cargo owner --add github:yourusername scarab-nav-protocol
cargo owner --add github:yourusername scarab-nav-client

“Version already published”

You cannot republish the same version. Bump the version number and try again.

”Client can’t find protocol version”

When publishing both crates, the protocol needs to be available on crates.io before the client can be published. The workflow handles this automatically with a 30-second delay. If publishing manually, wait a minute or two between publishing the protocol and client.

Workflow fails on tests

Fix the failing tests on main branch before creating a release tag. You can run tests locally:

cargo test --all-features --workspace

Workflow fails on clippy or format

Run these locally and fix issues:

cargo clippy --all-features --workspace -- -D warnings
cargo fmt --all

Pre-releases

For alpha, beta, or release candidates:

./scripts/release.sh 0.2.0-alpha.1 both

The GitHub Release will automatically be marked as a pre-release if the version contains alpha, beta, or rc.

Yanking a Release

If you need to remove a broken release from crates.io:

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

This prevents new projects from using it but doesn’t break existing users.

To un-yank:

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

Emergency Manual Publish

If the GitHub Actions workflow is broken and you need to publish urgently:

# Login to crates.io
cargo login
 
# Publish protocol first
cd crates/scarab-nav-protocol
cargo publish
 
# Wait for it to be available (check crates.io)
sleep 60
 
# Publish client
cd ../scarab-nav-client
cargo publish