Skip to content

RELEASE.md

Latest commit

 

History

History
208 lines (154 loc) · 4.4 KB

RELEASE.md

File metadata and controls

208 lines (154 loc) · 4.4 KB

Release Process Guide

This project uses cargo-release to automate the release workflow.

Setup

Cargo-release is already installed. The configuration is in release.toml.

Release Commands

1. Dry Run (Recommended First Step)

Preview what will happen without making changes:

cargo release patch

This shows:

  • Version bump (0.1.17 → 0.1.18)
  • Files to be modified
  • Git operations
  • Publishing steps

2. Perform Release

Execute the full release workflow:

cargo release patch --execute

This automatically:

  1. ✅ Bumps version in Cargo.toml
  2. ✅ Runs tests: cargo test
  3. ✅ Runs formatting check: cargo fmt --check
  4. ✅ Updates CHANGELOG.md
  5. ✅ Publishes to crates.io
  6. ✅ Creates release commit: "Release v0.1.18"
  7. ✅ Creates Git tag: v0.1.18
  8. ✅ Pushes commits and tags to remote

3. Release with Specific Version

Bump to a specific version (major, minor, patch):

# Patch release (0.1.17 → 0.1.18)
cargo release patch --execute

# Minor release (0.1.17 → 0.2.0)
cargo release minor --execute

# Major release (0.1.17 → 1.0.0)
cargo release major --execute

Note: Always specify a version level (patch/minor/major). Running cargo release without a level will try to re-release the current version.

4. Release Without Publishing to crates.io

If you want to skip publishing:

cargo release patch --execute --no-publish

5. Release Without Pushing to Git

For testing/staging:

cargo release patch --execute --no-push

What Gets Updated

Files Modified Automatically

  • Cargo.toml: Version number
  • CHANGELOG.md: New release section (if properly configured)
  • Git: Creates commit and annotated tag

Generated Release Commit

  • Commit message: "Release vX.Y.Z"
  • Includes: version bumps and CHANGELOG updates

Created Git Tag

  • Tag name: vX.Y.Z (e.g., v0.1.18)
  • Tag message: "Release vX.Y.Z"
  • Annotated tag for better tracking

Before Release

Ensure:

  1. ✅ All changes are committed: git status
  2. ✅ Tests pass: cargo test
  3. ✅ Code is formatted: cargo fmt
  4. ✅ You have push access to the remote repository
  5. ✅ crates.io credentials are configured (for publishing)

crates.io Publishing Setup

If this is your first time publishing to crates.io:

# Login to crates.io (interactive)
cargo login

# This creates/updates ~/.cargo/credentials.toml

Configuration

The release process is configured in release.toml:

  • changelog: Automatically update CHANGELOG.md
  • git.push: Push commits and tags to remote
  • git.tag-name: Tag format (v{{version}})
  • publish: Publish to crates.io

Example Release Workflow

# Step 1: Verify nothing to commit
$ git status
On branch main
nothing to commit

# Step 2: Preview the release
$ cargo release --dry-run
Prepared release of sofos v0.1.18

# Step 3: Execute release
$ cargo release patch --execute
Releasing sofos v0.1.18
- Bump version in Cargo.toml
- Run pre-release checks
- Update CHANGELOG.md
- Publish to crates.io
- Create release commit
- Create git tag v0.1.18
- Push to remote

# Step 4: Verify on GitHub
$ git tag
v0.1.17
v0.1.18  ← New tag

# Step 5: Verify on crates.io
# https://crates.io/crates/sofos

Troubleshooting

"No commits since last release"

You need new commits since the last tag:

git log v0.1.17..HEAD

"Failed to publish"

Check crates.io credentials:

cargo login

"Uncommitted changes"

All changes must be committed before release:

git status
git add .
git commit -m "message"

"Permission denied for push"

Ensure you have push access:

git push origin main  # Test push

Advanced: Customize CHANGELOG Updates

To have cargo-release automatically update CHANGELOG.md with conventional commit messages, ensure your commit messages follow the format:

feat: add new feature
fix: fix bug
docs: update documentation
refactor: refactor code

Then release will automatically categorize them in CHANGELOG.md.

Rollback Release

If something goes wrong:

# Undo the last commit
git reset --soft HEAD~1

# Delete the tag locally
git tag -d v0.1.18

# Delete the tag remotely
git push origin :refs/tags/v0.1.18

References