object-store-client 1.0.0

# Publishing the Rust Client to crates.io

Rust crates are published to crates.io, the official Rust package registry.

## Prerequisites

### 1. Create a crates.io Account

Go to https://crates.io and sign in with GitHub.

### 2. Get Your API Token

1. Go to https://crates.io/me
2. Click "New Token" under "API Tokens"
3. Give it a name (e.g., "object-storage-client")
4. Copy the token

### 3. Login to crates.io

```bash
cargo login <your-token>
```

This stores your token in `~/.cargo/credentials.toml`.

## Pre-Publication Checklist

### 1. Verify Package Metadata

Check `Cargo.toml` has all required fields:
- ✓ name
- ✓ version
- ✓ authors
- ✓ license (must match repo license)
- ✓ description
- ✓ repository
- ✓ homepage
- ✓ documentation
- ✓ readme
- ✓ keywords (max 5)
- ✓ categories

### 2. Test the Package

```bash
cd clients/rust

# Run all tests
cargo test

# Check for issues
cargo clippy -- -D warnings

# Verify documentation builds
cargo doc --no-deps --open

# Ensure it builds
cargo build --release
```

### 3. Check Package Contents

```bash
# See what files will be included
cargo package --list

# Do a dry run of packaging
cargo package --dry-run
```

This creates a `.crate` file in `target/package/` to verify what will be published.

### 4. Verify README Renders Correctly

The README will be shown on crates.io. Check that:
- Code examples are correct
- Links work
- Formatting looks good

## Publishing Steps

### 1. Update Version (if needed)

Edit `Cargo.toml`:
```toml
version = "0.1.0"  # or 0.1.1, 0.2.0, etc.
```

Follow semantic versioning:
- `0.x.y` - Pre-1.0, breaking changes allowed
- `1.x.y` - Stable, no breaking changes in minor/patch

### 2. Publish to crates.io

```bash
cd clients/rust

# Dry run first (recommended)
cargo publish --dry-run

# Actually publish
cargo publish
```

**Note**: Publishing is permanent! You cannot delete or replace a version once published.

### 3. Verify Publication

After a few minutes, your crate will be available:
- **crates.io**: https://crates.io/crates/object-store-client
- **docs.rs**: https://docs.rs/object-store-client (docs auto-build)

Users can now install it:
```bash
cargo add object-store-client
```

### 4. Tag the Release in Git

```bash
cd ../..  # Back to repo root

git add clients/rust/
git commit -m "Release Rust client v0.1.0"
git push

git tag clients/rust/v0.1.0
git push origin clients/rust/v0.1.0
```

## Updating the Crate

### For Bug Fixes (Patch Version)

```toml
version = "0.1.1"
```

```bash
cargo publish
```

### For New Features (Minor Version)

```toml
version = "0.2.0"
```

```bash
cargo publish
```

### For Breaking Changes (Major Version)

```toml
version = "1.0.0"
```

```bash
cargo publish
```

## Troubleshooting

### "crate name is already taken"

The name `object-store-client` might be taken. Try:
- `metorial-object-storage`
- `object-storage-rs`
- Check availability: https://crates.io/crates/your-name-here

### "file not found in package"

Add to `Cargo.toml`:
```toml
[package]
include = [
    "src/**/*",
    "Cargo.toml",
    "README.md",
]
```

### "documentation failed to build"

Check that all dependencies are published and examples compile.

## Publishing Checklist Script

```bash
#!/bin/bash
# publish-rust-client.sh

set -e

cd clients/rust

echo "Running tests..."
cargo test

echo "Running clippy..."
cargo clippy -- -D warnings

echo "Building docs..."
cargo doc --no-deps

echo "Checking package..."
cargo package --dry-run

echo "Ready to publish!"
echo "Run: cargo publish"
```

## After Publishing

1. Announce the release (GitHub releases, social media, etc.)
2. Update the main README with the correct version
3. Monitor https://docs.rs for documentation build status
4. Check for any issues on GitHub

## Yanking a Version (Emergency Only)

If you published a broken version:

```bash
cargo yank --vers 0.1.0 object-store-client
```

This prevents new users from downloading it, but existing users can still use it.

To un-yank:
```bash
cargo yank --undo --vers 0.1.0 object-store-client
```

## Best Practices

1. **Test before publishing**: Run full test suite
2. **Use semantic versioning**: Follow semver strictly
3. **Write good docs**: Examples, API docs, README
4. **Keep changelog**: Document changes between versions
5. **Don't rush**: There's no undo for publishing
6. **Start with 0.x**: Use pre-1.0 versions while API is unstable