# Publishing to Cargo (crates.io)
This document outlines the steps to publish the `gemini_crate` library to crates.io.
## Pre-Publication Checklist
### 1. Repository Setup
- [ ] **Update Cargo.toml URLs**: Replace `YOUR_USERNAME` with your actual GitHub username
- `homepage = "https://github.com/YOUR_USERNAME/gemini_crate"`
- `repository = "https://github.com/YOUR_USERNAME/gemini_crate"`
- [ ] **Push to GitHub**: Ensure all code is committed and pushed to your repository
- [ ] **Create GitHub repository**: Make sure the repository exists and is public
### 2. Documentation Review
- [ ] **README.md**: Review and update badges, examples, and installation instructions
- [ ] **USAGE.md**: Ensure all examples are current and working
- [ ] **CHANGELOG.md**: Document all features and changes for version 0.1.0
- [ ] **License files**: Verify `LICENSE-MIT` and `LICENSE-APACHE` are present and correct
### 3. Code Quality Checks
Run these commands and ensure they all pass:
```bash
# Check compilation
cargo check
# Run all tests
cargo test
# Check code style
cargo clippy
# Format code
cargo fmt
# Build examples
cargo build --examples
# Verify package contents
cargo package --list --allow-dirty
```
### 4. API Key Setup
- [ ] **Environment file**: Ensure `.env.example` exists with proper template
- [ ] **Documentation**: Verify API key setup instructions are clear in README
- [ ] **Security**: Confirm `.env` is in `.gitignore` and not committed
### 5. Examples Verification
Test that all examples work:
- [ ] `cargo run --example simple_chat` (requires valid API key)
- [ ] `cargo run --example list_models` (requires valid API key)
- [ ] `cargo run --example batch_processing` (requires valid API key)
### 6. Version Management
- [ ] **Semantic versioning**: Confirm version `0.1.0` is appropriate
- [ ] **Rust version**: Verify `rust-version = "1.70"` is correct minimum
- [ ] **Dependencies**: Ensure all dependency versions are appropriate
### 7. Cargo.io Account Setup
- [ ] **Create account**: Sign up at [crates.io](https://crates.io/) with GitHub
- [ ] **API token**: Generate API token from crates.io settings
- [ ] **Login**: Run `cargo login` with your API token
## Publishing Steps
### Step 1: Final Preparation
```bash
# Clean build
cargo clean
# Final test
cargo test
# Final lint check
cargo clippy -- -D warnings
# Format code
cargo fmt
```
### Step 2: Package and Verify
```bash
# Create package (dry run)
cargo package --allow-dirty
# Verify package contents
cargo package --list --allow-dirty
```
### Step 3: Publish
```bash
# Publish to crates.io
cargo publish --allow-dirty
```
**Note**: The `--allow-dirty` flag is needed if you have uncommitted changes. Consider committing all changes first.
## Post-Publication
### Immediate Tasks
- [ ] **Verify publication**: Check that the crate appears on [crates.io](https://crates.io/crates/gemini_crate)
- [ ] **Test installation**: Try `cargo add gemini_crate` in a new project
- [ ] **Documentation**: Verify docs appear on [docs.rs](https://docs.rs/gemini_crate)
### Repository Updates
- [ ] **Update README**: Fix any badges that may have changed
- [ ] **Tag release**: Create a git tag for version 0.1.0
- [ ] **GitHub release**: Create a GitHub release with changelog
### Future Considerations
- [ ] **CI/CD**: Set up GitHub Actions for automated testing
- [ ] **Security**: Consider setting up security advisories
- [ ] **Maintenance**: Plan regular updates for dependencies
## Troubleshooting
### Common Issues
**"crate name is already taken"**
- Choose a different, unique name in `Cargo.toml`
- Check [crates.io](https://crates.io/) for name availability
**"repository field should be a URL"**
- Ensure repository URL is valid and accessible
- Use `https://` format, not `git://`
**"missing license file"**
- Verify `LICENSE-MIT` and `LICENSE-APACHE` files exist
- Ensure license field in Cargo.toml matches actual licenses
**"failed to verify package"**
- Check that all dependencies build successfully
- Ensure all file paths in Cargo.toml are correct
**"authentication required"**
- Run `cargo login` with your crates.io API token
- Verify token has appropriate permissions
### Package Size Issues
If package is too large:
- Review `exclude` list in `Cargo.toml`
- Add unnecessary files to exclude list:
```toml
exclude = [
".env*",
".zed/",
"target/",
"examples/test_data/",
"docs/",
"*.log",
]
```
### Network Issues (Starlink/Satellite Internet)
For unreliable connections:
- Use `cargo publish --allow-dirty --timeout 300` for longer timeout
- Retry the command if it fails due to network issues
- Consider using a stable internet connection for initial publish
## Version Updates
For future versions:
1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Run full test suite
4. Commit changes
5. Run `cargo publish`
6. Tag the release: `git tag v0.1.1`
7. Push tags: `git push --tags`
## Resources
- [Cargo Book - Publishing](https://doc.rust-lang.org/cargo/reference/publishing.html)
- [crates.io Guide](https://doc.rust-lang.org/cargo/reference/publishing.html)
- [Semantic Versioning](https://semver.org/)
- [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
## Success Checklist
After successful publication:
- [ ] Crate is visible on crates.io
- [ ] Documentation builds on docs.rs
- [ ] Installation works: `cargo add gemini_crate`
- [ ] Basic functionality test passes
- [ ] GitHub repository is updated with release tag
- [ ] Community can discover and use the crate