# Version Bump Guide
This guide explains how to use the automated version bumping workflows and tools for Rust crates in the Northroot organization.
## Overview
Version bumping can be done in two ways:
1. **GitHub Actions Workflow** (recommended for CI/CD)
2. **Local Shell Script** (for manual local execution)
Both methods automatically:
- Update `Cargo.toml` version
- Update `CHANGELOG.md` (if present)
- Create git tags
- Trigger publish workflows
## GitHub Actions Workflow
### Using the Workflow
1. Go to your repository on GitHub
2. Navigate to **Actions** → **Version Bump**
3. Click **Run workflow**
4. Select bump type:
- **patch**: Bug fixes (0.1.0 → 0.1.1)
- **minor**: New features (0.1.0 → 0.2.0)
- **major**: Breaking changes (0.1.0 → 1.0.0)
5. Click **Run workflow**
The workflow will:
- Calculate new version
- Update `Cargo.toml`
- Update `CHANGELOG.md`
- Commit changes
- Create git tag
- Push to repository
- Automatically trigger publish workflow
### Workflow Files
- **Reusable workflow**: `.github/workflows/rust-version-bump.yml`
- **Repository trigger**: `.github/workflows/version-bump.yml`
## Local Shell Script
### Usage
```bash
./scripts/version-bump.sh [patch|minor|major]
```
### Example
```bash
# Bump patch version (0.2.0 → 0.2.1)
./scripts/version-bump.sh patch
# Bump minor version (0.2.0 → 0.3.0)
./scripts/version-bump.sh minor
# Bump major version (0.2.0 → 1.0.0)
./scripts/version-bump.sh major
```
### After Running the Script
The script updates files but doesn't commit. You need to:
```bash
# Review changes
git diff
# Commit
git add Cargo.toml CHANGELOG.md
git commit -m "chore: bump version to X.Y.Z"
# Tag
git tag -a vX.Y.Z -m "Release X.Y.Z"
# Push
git push origin main
git push origin vX.Y.Z
```
## CHANGELOG.md Format
The tools expect `CHANGELOG.md` to follow this format:
```markdown
# Changelog
All notable changes to this project will be documented in this file.
## [Unreleased]
### Added
- New feature
[Unreleased]: https://github.com/org/repo/compare/v0.2.0...HEAD
## [0.2.0] - 2025-01-15
### Changed
- Updated dependency
[0.2.0]: https://github.com/org/repo/compare/v0.1.0...v0.2.0
```
The tools will:
- Move `[Unreleased]` content to a new version section
- Add date to new version section
- Update comparison links automatically
## Organization-Level Secrets Setup
To share secrets across repositories in the organization:
### Setting Up CRATES_IO_TOKEN
1. Go to **Organization Settings** → **Secrets and variables** → **Actions**
2. Click **New organization secret**
3. Name: `CRATES_IO_TOKEN`
4. Value: Your crates.io API token
5. Select repositories that should have access
6. Click **Add secret**
### Benefits
- **Single source of truth**: Update token once, applies to all repos
- **Easier management**: No need to set secrets per repository
- **Security**: Centralized access control
### Repository-Level Override
If a repository needs a different token, you can still set it at the repository level. Repository secrets take precedence over organization secrets.
## Troubleshooting
### Workflow Fails with "CRATES_IO_TOKEN not found"
1. Check that the secret is set at organization or repository level
2. Verify the secret name is exactly `CRATES_IO_TOKEN`
3. Ensure the repository has access to organization secrets
### Version Already Exists
If you try to publish a version that already exists:
- The publish workflow will fail
- Update to a new version and try again
- Check existing versions: `cargo search <crate-name>`
### CHANGELOG.md Not Updated
- Ensure `CHANGELOG.md` exists
- Check that it has a `## [Unreleased]` section
- Verify the file format matches the expected structure
## Best Practices
1. **Always bump version before merging major changes**
2. **Use semantic versioning**: patch for fixes, minor for features, major for breaking changes
3. **Keep CHANGELOG.md up to date** with changes under `[Unreleased]`
4. **Test locally** before pushing tags
5. **Review generated changes** before committing
## Related Documentation
- [Semantic Versioning](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [GitHub Actions Documentation](https://docs.github.com/en/actions)