advanced-algorithms 0.1.0

# Publishing Your Rust Library to crates.io

This guide will walk you through the process of making the Advanced Algorithms library available for others to use via [crates.io](https://crates.io), the official Rust package registry.

## Prerequisites

Before publishing, ensure you have:

1. **A crates.io Account**: Create one at [crates.io](https://crates.io) (sign in with GitHub)
2. **Cargo Installed**: Comes with Rust (verify with `cargo --version`)
3. **API Token**: Generate from your crates.io account settings

## Step 1: Prepare Your Package

### 1.1 Update Cargo.toml

Ensure your `Cargo.toml` has all required metadata:

```toml
[package]
name = "advanced-algorithms"
version = "0.1.0"
edition = "2021"
authors = ["Your Name <your.email@example.com>"]
license = "MIT OR Apache-2.0"
description = "A comprehensive library of advanced algorithms for numerical analysis, linear algebra, cryptography, optimization, and graph theory"
documentation = "https://docs.rs/advanced-algorithms"
homepage = "https://github.com/yourusername/advanced-algorithms"
repository = "https://github.com/yourusername/advanced-algorithms"
keywords = ["algorithms", "numerical", "optimization", "cryptography", "linear-algebra"]
categories = ["algorithms", "mathematics", "science"]
readme = "README.md"
```

**Important Fields:**

- `name`: Must be unique on crates.io
- `version`: Follow [Semantic Versioning](https://semver.org/)
- `license`: Choose an OSI-approved license
- `description`: Max 200 characters
- `keywords`: Max 5 keywords
- `categories`: Choose from [crates.io categories](https://crates.io/categories)

### 1.2 Add License Files

Create license files in your project root:

**LICENSE-MIT:**

```
MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

[... full MIT license text ...]
```

**LICENSE-APACHE:**

```
[... full Apache 2.0 license text ...]
```

### 1.3 Verify Package Contents

Check what will be included in your package:

```bash
cargo package --list
```

Exclude unnecessary files in `Cargo.toml`:

```toml
[package]
exclude = [
    ".github/*",
    "benchmarks/*",
    "examples/large_data/*",
    "*.tmp",
]
```

## Step 2: Quality Checks

### 2.1 Run Tests

Ensure all tests pass:

```bash
cargo test --all-features
```

### 2.2 Check Documentation

Generate and review documentation:

```bash
cargo doc --no-deps --open
```

Ensure all public APIs are documented:

```bash
cargo doc --no-deps 2>&1 | grep warning
```

### 2.3 Run Clippy

Fix any linting issues:

```bash
cargo clippy --all-features -- -D warnings
```

### 2.4 Format Code

Ensure code is formatted:

```bash
cargo fmt --all -- --check
```

### 2.5 Verify Package Build

Test that your package builds correctly:

```bash
cargo package
cargo publish --dry-run
```

This creates a `.crate` file in `target/package/` without publishing.

## Step 3: Set Up API Token

### 3.1 Get Your Token

1. Go to [crates.io/settings/tokens](https://crates.io/settings/tokens)
2. Click "New Token"
3. Give it a name (e.g., "publishing-token")
4. Copy the generated token

### 3.2 Login to crates.io

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

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

**Security Note:** Never commit your API token or credentials file to version control!

## Step 4: Publish Your Crate

### 4.1 First Publication

```bash
cargo publish
```

This will:

1. Package your crate
2. Upload it to crates.io
3. Build documentation on docs.rs
4. Make it available via `cargo add` and in Cargo.toml

### 4.2 Monitor the Process

- Check upload status on your terminal
- View your crate at `https://crates.io/crates/advanced-algorithms`
- Documentation builds automatically at `https://docs.rs/advanced-algorithms`

## Step 5: Post-Publication

### 5.1 Verify Installation

Test that others can install your crate:

```bash
# In a new project
cargo new test-install
cd test-install
cargo add advanced-algorithms
```

### 5.2 Update README Badges

Add badges to your README:

```markdown
[![Crates.io](https://img.shields.io/crates/v/advanced-algorithms.svg)](https://crates.io/crates/advanced-algorithms)
[![Documentation](https://docs.rs/advanced-algorithms/badge.svg)](https://docs.rs/advanced-algorithms)
[![Downloads](https://img.shields.io/crates/d/advanced-algorithms.svg)](https://crates.io/crates/advanced-algorithms)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE)
```

## Updating Your Crate

### Version Bumping

Follow Semantic Versioning:

- **Patch** (0.1.0 → 0.1.1): Bug fixes
- **Minor** (0.1.0 → 0.2.0): New features (backward compatible)
- **Major** (0.1.0 → 1.0.0): Breaking changes

Update version in `Cargo.toml`:

```toml
[package]
version = "0.2.0"
```

### Publishing Updates

```bash
# Update version in Cargo.toml
# Update CHANGELOG.md
git add Cargo.toml CHANGELOG.md
git commit -m "Bump version to 0.2.0"
git tag v0.2.0
git push origin main --tags

cargo publish
```

## Best Practices

### 1. Maintain a Changelog

Create `CHANGELOG.md`:

```markdown
# Changelog

## [0.2.0] - 2025-01-15

### Added

- New algorithm: Conjugate Gradient optimization
- Parallel implementation of SVD

### Fixed

- Numerical stability issue in QR decomposition

## [0.1.0] - 2025-01-01

### Added

- Initial release
```

### 2. Use Continuous Integration

Example GitHub Actions workflow (`.github/workflows/ci.yml`):

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - run: cargo test --all-features
      - run: cargo clippy -- -D warnings
      - run: cargo fmt -- --check
```

### 3. Semantic Versioning

- Before 1.0.0: Breaking changes in minor versions are acceptable
- After 1.0.0: Follow strict semver (breaking changes = major bump)

### 4. Documentation

- Document all public APIs
- Provide examples in doc comments
- Keep README.md updated
- Link to external resources

### 5. Deprecation

When removing features:

```rust
#[deprecated(since = "0.3.0", note = "Use `new_function` instead")]
pub fn old_function() {
    // ...
}
```

## Troubleshooting

### "name already taken"

Choose a different name or request ownership if the crate is abandoned.

### "version already published"

You cannot re-publish the same version. Bump the version number.

### Documentation build fails

Check docs.rs build logs at `https://docs.rs/crate/advanced-algorithms/latest/builds`

### Rate limiting

You can publish a new version of the same crate once every 10 minutes.

## Yanking a Release

If you published a broken version:

```bash
cargo yank --vers 0.1.1
```

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

To un-yank:

```bash
cargo yank --vers 0.1.1 --undo
```

## Resources

- [The Cargo Book - Publishing on crates.io](https://doc.rust-lang.org/cargo/reference/publishing.html)
- [crates.io Policies](https://crates.io/policies)
- [Semantic Versioning](https://semver.org/)
- [API Guidelines](https://rust-lang.github.io/api-guidelines/)
- [docs.rs Documentation](https://docs.rs/about)

## Support

If you encounter issues:

1. Check [crates.io status](https://status.crates.io/)
2. Review [Cargo documentation](https://doc.rust-lang.org/cargo/)
3. Ask in [Rust Users Forum](https://users.rust-lang.org/)
4. Join [Rust Discord](https://discord.gg/rust-lang)

## Checklist

Before publishing:

- [ ] All tests pass (`cargo test`)
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Code is formatted (`cargo fmt`)
- [ ] Documentation builds (`cargo doc`)
- [ ] README.md is complete
- [ ] License files are present
- [ ] Cargo.toml metadata is complete
- [ ] Version number is correct
- [ ] CHANGELOG.md is updated
- [ ] Git tag created
- [ ] Dry run successful (`cargo publish --dry-run`)

After publishing:

- [ ] Crate appears on crates.io
- [ ] Documentation builds on docs.rs
- [ ] Test installation in fresh project
- [ ] Update repository README badges
- [ ] Announce on social media/forums
- [ ] Add to awesome-rust lists (if applicable)

Good luck with your publication! 🎉