# Publishing to crates.io
## Prerequisites
1. **Get a crates.io API token:**
- Visit https://crates.io/settings/tokens
- Create a new token with "publish-update" scope
- Copy the token (you won't see it again!)
2. **Add token to GitLab CI/CD variables:**
- Go to your GitLab project: Settings → CI/CD → Variables
- Click "Add variable"
- Key: `CARGO_REGISTRY_TOKEN`
- Value: (paste your crates.io token)
- ✅ Check "Mask variable" (hides it in logs)
- ✅ Check "Protected" (only available on protected branches)
- Click "Add variable"
## Publishing Process
### 1. Update Version
Edit `Cargo.toml`:
```toml
version = "0.2.0" # Update this
```
### 2. Update CHANGELOG (recommended)
Document what changed in this version.
### 3. Commit and Push
```bash
git add Cargo.toml CHANGELOG.md
git commit -m "chore: bump version to 0.2.0"
git push origin main
```
### 4. Manual Publish via GitLab UI
1. Go to your GitLab project → CI/CD → Pipelines
2. Wait for the pipeline to run (all tests must pass)
3. Find the `publish:crates-io` job in the **publish** stage
4. Click the ▶️ play button to manually trigger it
5. Watch the job logs to confirm success
### 5. (Optional) Tag the Release
After successful publish:
```bash
git tag v0.2.0
git push origin v0.2.0
```
## Pipeline Stages
The CI/CD pipeline runs automatically on every push:
### ✅ Check Stage
- `fmt` - Code formatting check
- `clippy` - Lint checks
### 🧪 Test Stage
- `test` - Tests with default features
- `test-all-features` - Tests with all features
- `test-std` - Tests with std only
- `test-hash` - Tests with hash feature
- `test-emoji` - Tests with emoji feature
- `test-ansi-colors` - Tests with ansi-colors feature
- `test-serde` - Tests with serde feature
### 🔨 Build Stage
- `doc` - Build documentation
- `examples` - Build all examples
- `publish-check` - Dry-run of publishing (verifies package is ready)
### 🚀 Publish Stage (Manual Only)
- `publish:crates-io` - **Manual trigger** - Publishes to crates.io
## Testing Before Publishing
To test locally that your package is ready:
```bash
# Dry-run (doesn't actually publish)
cargo publish --dry-run
# Verify all features work
cargo test --all-features
# Check documentation builds
cargo doc --all-features --no-deps
```
## Troubleshooting
### "Missing CARGO_REGISTRY_TOKEN"
- Make sure you added the token to GitLab CI/CD variables
- Check that it's not expired on crates.io
- Verify the variable name is exactly `CARGO_REGISTRY_TOKEN`
### "Package already published"
- You can't republish the same version
- Bump the version number in `Cargo.toml`
- Versions are immutable on crates.io
### "Dirty working directory"
- The pipeline uses `--allow-dirty` flag
- This allows publishing even with uncommitted changes
- **Best practice:** Commit everything before publishing
### Tests fail
- Fix the failing tests before attempting to publish
- The publish job requires all test jobs to pass (`needs:` section)
## Version Numbering
Follow [Semantic Versioning](https://semver.org/):
- **MAJOR** (1.0.0): Breaking changes
- **MINOR** (0.2.0): New features, backward compatible
- **PATCH** (0.1.1): Bug fixes, backward compatible
Current version: **0.2.0**
- Added emoji feature flag
- Added semantic methods
- Modularized codebase
- Breaking change: emoji now requires feature flag