# Release Checklist
This document outlines the complete process for releasing a new version of waddling-errors.
## Pre-Release Checklist
### 1. Code Quality
- [ ] All tests pass locally: `cargo test --all-features`
- [ ] Clippy is happy: `cargo clippy --all-features -- -D warnings`
- [ ] Code is formatted: `cargo fmt --all -- --check`
- [ ] Documentation builds: `cargo doc --all-features --no-deps`
- [ ] All examples run successfully
### 2. Version Bump
Determine version number using [Semantic Versioning](https://semver.org/):
- **MAJOR** (1.0.0): Breaking API changes
- **MINOR** (0.X.0): New features, backward compatible
- **PATCH** (0.1.X): Bug fixes, backward compatible
Update version in:
- [ ] `Cargo.toml` - version field
- [ ] `README.md` - installation examples (if applicable)
- [ ] `FEATURE_FLAGS.md` - installation examples (if applicable)
### 3. Documentation
- [ ] Update `CHANGELOG.md` with release notes
- [ ] Review and update `README.md` if needed
- [ ] Check all doc comments are accurate
- [ ] Verify examples in documentation still work
### 4. Test Matrix
Run comprehensive tests:
```bash
# Minimal build
cargo test --no-default-features
# Individual features
cargo test --no-default-features --features emoji
cargo test --no-default-features --features ansi-colors
cargo test --features hash
cargo test --features serde
# All features
cargo test --all-features
# Doc tests
cargo test --doc --all-features
```
### 5. Dry Run
Test that the package is ready for publishing:
```bash
cargo publish --dry-run
```
Fix any warnings or errors before proceeding.
## Release Process
### Step 1: Create Release Commit
```bash
# Add all changes
git add Cargo.toml CHANGELOG.md README.md
# Commit with version bump
git commit -m "chore: release v0.2.0"
# Push to main
git push origin main
```
### Step 2: Wait for CI/CD Pipeline
1. Go to GitLab → CI/CD → Pipelines
2. Wait for the pipeline to complete successfully
3. Verify all stages pass:
- ✅ Check (fmt, clippy)
- ✅ Test (all feature combinations)
- ✅ Build (docs, examples)
- ⏸️ Publish (manual)
### Step 3: Publish to crates.io
**Via GitLab CI/CD (Recommended):**
1. In the pipeline view, find the `publish:crates-io` job
2. Click the ▶️ play button to trigger manual publish
3. Monitor the job logs for success
4. Verify at https://crates.io/crates/waddling-errors
**Via Command Line (Alternative):**
```bash
cargo publish --token $YOUR_CRATES_IO_TOKEN
```
### Step 4: Create Git Tag
After successful publish:
```bash
# Create annotated tag
git tag -a v0.2.0 -m "Release v0.2.0
- Added emoji feature flag
- Added semantic methods (is_blocking, is_positive, etc.)
- Modularized codebase into 4 files
- Added ANSI colors behind feature flag
- Breaking: emoji now requires feature flag"
# Push tag
git push origin v0.2.0
```
### Step 5: Create GitLab Release
1. Go to GitLab → Deployments → Releases → New Release
2. Select tag: `v0.2.0`
3. Release title: `v0.2.0 - <Short Description>`
4. Copy changelog entries into description
5. Add links:
- crates.io: https://crates.io/crates/waddling-errors/0.2.0
- docs.rs: https://docs.rs/waddling-errors/0.2.0
6. Publish release
## Post-Release
### Verification
- [ ] Package appears on crates.io
- [ ] Documentation built on docs.rs
- [ ] Can install: `cargo add waddling-errors@0.2.0`
- [ ] Git tag is pushed
- [ ] GitLab release is created
### Communication
- [ ] Announce in project README (if significant)
- [ ] Update dependent projects (QuackPatch, etc.)
- [ ] Share in relevant communities (if major release)
## Rollback Procedure
If something goes wrong:
### Before Publishing
- Simply fix the issue and re-run the checklist
### After Publishing to crates.io
- **You cannot unpublish or change published versions**
- **You can only yank versions:** `cargo yank --vers 0.2.0`
- Yanking prevents new projects from using it, but existing users can still access it
- Immediately publish a fixed version (e.g., 0.2.1)
## Version History
| 0.2.0 | 2025-10-25 | Minor | Added emoji/ANSI features, semantic methods |
| 0.1.0 | TBD | Initial | Initial release with core error code standard |
## Maintainer Notes
### First-Time Setup
See `docs/maintenance/PUBLISHING.md` for:
- How to get crates.io API token
- How to set up GitLab CI/CD variables
- Detailed troubleshooting
### GitLab CI/CD Token
The `CARGO_REGISTRY_TOKEN` is stored in:
- GitLab: Settings → CI/CD → Variables
- Marked as "Masked" and "Protected"
- Should be periodically rotated for security
### Release Cadence
- **Patch releases**: As needed for bug fixes
- **Minor releases**: Every 2-4 weeks for new features
- **Major releases**: When breaking changes are necessary
### Emergency Hotfix Process
For critical bugs in production:
1. Create hotfix branch from tag: `git checkout -b hotfix/0.2.1 v0.2.0`
2. Fix the bug
3. Update version to 0.2.1
4. Follow release process (expedited)
5. Merge back to main