Bump Release

Bump Release

Overview

This skill executes the complete automated release workflow for Rust projects that follow Conventional Emoji Commits. Execute this workflow when a user requests to create a release, bump the version, or publish a new version of the project.

The workflow:

1. Analyzes all commits since the last release tag
2. Determines the appropriate semantic version bump (MAJOR, MINOR, PATCH, or NONE)
3. Updates version fields in Cargo.toml file(s)
4. Generates a changelog section using git-cliff
5. Creates a release commit and annotated git tag
6. Pushes changes to GitHub
7. Creates a GitHub Release with generated changelog

When to Use This Skill

Use this skill when the user:

• Requests to "create a release" or "cut a release"
• Asks to "bump the version" or "publish a new version"
• Wants to "see what the next release would be" (use dry-run mode)
• Asks about the release process or workflow
• Requests to "create a GitHub release"
• Mentions tagging a version

Examples:

• "Create a new release for this project"
• "Bump the version and publish"
• "What would the next release version be?"
• "Cut a release based on recent commits"
• "Create version 1.2.0"

Prerequisites

Before executing the release workflow, verify the following requirements are met:

Required Tools

Check that these tools are installed:

• git - Version control
• gh (GitHub CLI) - For creating GitHub releases
• git-cliff - Changelog generation (install with cargo install git-cliff)
• python3 (version 3.7+) - For analysis scripts
• cargo - Rust build tool (for validation)

Installation check:

command -v git && command -v gh && command -v git-cliff && command -v python3 && command -v cargo

GitHub Authentication

Verify GitHub CLI is authenticated:

gh auth status

If not authenticated, run:

gh auth login

Repository State

Ensure:

• Working directory is clean (no uncommitted changes)
• Currently on the main branch (or configured release branch)
• Have permission to push to the repository

git-cliff Configuration (Optional)

While optional, having a .cliff.toml or cliff.toml configuration file at the project root improves changelog formatting. The skill will use default git-cliff configuration if no config file exists.

Workflow Decision Tree

Choose the appropriate workflow based on the user's request:

User requests release?
├─ Yes → Determine workflow type:
│  ├─ "What would the next release be?" → Execute DRY-RUN workflow
│  ├─ "Create a release but don't push" → Execute LOCAL-ONLY workflow
│  ├─ "Create a pre-release" → Execute PRERELEASE workflow
│  └─ "Create a release" → Execute FULL workflow
└─ No → Not applicable for this skill

Release Workflows

Full Release Workflow (Default)

Execute this workflow for standard releases that will be pushed to GitHub.

Steps:

1. Verify prerequisites - Check all required tools are installed and repository state is valid

2. Execute the main script:

   ./scripts/bump_release.sh
   

3. The script will automatically:

   • Fetch latest tags from remote
   • Analyze commits since last release tag
   • Parse commit messages for Conventional Emoji Commit types
   • Determine semantic version bump (MAJOR for breaking changes, MINOR for features, PATCH for fixes)
   • Display analysis summary and new version
   • Update version in all Cargo.toml files (workspace root and members)
   • Run cargo check to validate changes
   • Generate changelog section using git-cliff
   • Update or create CHANGELOG.md file
   • Create release commit with format: 🔖 release: bump version to vX.Y.Z
   • Create annotated git tag (e.g., v1.2.3)
   • Push commit and tag to remote
   • Create GitHub Release with changelog

4. Verify the release:

   • Check GitHub Releases page for new release
   • Verify version in Cargo.toml is updated
   • Review CHANGELOG.md for new entry

Dry-Run Workflow (Preview)

Execute this workflow when the user wants to see what would happen without making any changes.

Steps:

1. Execute with dry-run flag:

   ./scripts/bump_release.sh --dry-run
   

2. Review output:

   • Current version
   • Commits since last release
   • Determined bump type (MAJOR, MINOR, PATCH, or NONE)
   • New version that would be created
   • Changelog content that would be generated
   • Files that would be modified

3. Explain findings to user:

   • "Based on X commits since vY.Z.W, the next release would be vA.B.C"
   • "This is a [MAJOR/MINOR/PATCH] bump because [reason]"
   • Show commit types found (features, fixes, breaking changes)
   • Preview changelog content

4. If no releasable commits:

   • Inform user: "No releasable commits found since last release"
   • Explain: "Only found documentation, style, refactoring, or test commits"
   • Suggest: "Need at least one feat, fix, or breaking change commit"

Local-Only Workflow

Execute this workflow when the user wants to prepare a release locally without pushing to GitHub.

Steps:

1. Execute with no-push flag:

   ./scripts/bump_release.sh --no-push
   

2. The script will:

   • Perform all release steps locally
   • Create commit and tag
   • NOT push to remote
   • NOT create GitHub Release

3. Inform user:

   • "Release prepared locally as vX.Y.Z"
   • "To push: git push && git push origin vX.Y.Z"
   • "To create GitHub release: gh release create vX.Y.Z"

Pre-Release Workflow

Execute this workflow for alpha, beta, or release candidate versions.

Steps:

1. Execute with prerelease flag:

   ./scripts/bump_release.sh --prerelease
   

2. The script will:

   • Perform full release workflow
   • Mark GitHub Release as "pre-release"
   • This prevents it from being marked as "Latest"

3. Note: Pre-release versions should follow semantic versioning prerelease format:

   • 1.0.0-alpha.1
   • 1.0.0-beta.2
   • 1.0.0-rc.1

Custom Branch Workflow

Execute this workflow when releasing from a branch other than main.

Steps:

1. Specify branch:

   ./scripts/bump_release.sh --branch develop
   

2. Use case: For projects that release from different branches (e.g., develop, release, stable)

Commit Analysis Logic

The skill parses Conventional Emoji Commits to determine version bumps. Refer to references/conventional-emoji-commits.md for complete details.

Quick reference:

Priority: MAJOR > MINOR > PATCH > NONE

When multiple commits exist, the highest priority bump is used.

Scripts Reference

analyze_commits.py

Analyzes git commits since last release and determines version bump.

Usage:

./scripts/analyze_commits.py [OPTIONS]

Options:

• --current-version VERSION - Specify current version (default: last git tag or 0.0.0)
• --format {bump-type|new-version|json} - Output format (default: bump-type)
• --verbose - Show detailed analysis

Examples:

# Get bump type
./scripts/analyze_commits.py --format bump-type
# Output: major, minor, patch, or none

# Get new version
./scripts/analyze_commits.py --format new-version
# Output: 1.2.3

# Get full JSON analysis
./scripts/analyze_commits.py --format json
# Output: {"current_version": "1.2.2", "bump_type": "minor", "new_version": "1.3.0", ...}

# Verbose mode shows commit analysis
./scripts/analyze_commits.py --verbose

Use this script when:

• User asks "What would the next version be?"
• Need to analyze commits before executing release
• Debugging commit parsing issues

bump_version.py

Updates version field in Cargo.toml file(s).

Usage:

./scripts/bump_version.py NEW_VERSION [OPTIONS]

Options:

• --root PATH - Project root directory (default: current directory)
• --dry-run - Preview changes without modifying files
• --workspace-deps - Also update workspace dependency version references
• --verbose - Show detailed output

Examples:

# Update version to 1.2.3
./scripts/bump_version.py 1.2.3

# Dry-run to preview
./scripts/bump_version.py 1.2.3 --dry-run

# Update workspace dependencies too
./scripts/bump_version.py 1.2.3 --workspace-deps

# Specify project root
./scripts/bump_version.py 1.2.3 --root /path/to/project

Use this script when:

• Manually updating versions without full release workflow
• Need to update only version without commit/tag/changelog
• Testing version update logic

bump_release.sh

Main orchestration script that executes complete release workflow.

Usage:

./scripts/bump_release.sh [OPTIONS]

Options:

• -d, --dry-run - Preview without making changes
• -s, --skip-checks - Skip pre-release checks (dirty tree, branch)
• -n, --no-push - Local release only (don't push or create GitHub release)
• -p, --prerelease - Mark as pre-release on GitHub
• -b, --branch BRANCH - Specify main branch (default: main)
• -c, --changelog FILE - Specify changelog file (default: CHANGELOG.md)
• -h, --help - Show help message

Examples:

# Standard release
./scripts/bump_release.sh

# Preview what would happen
./scripts/bump_release.sh --dry-run

# Create pre-release
./scripts/bump_release.sh --prerelease

# Release from develop branch
./scripts/bump_release.sh --branch develop

# Prepare locally without pushing
./scripts/bump_release.sh --no-push

# Skip checks (useful in CI)
./scripts/bump_release.sh --skip-checks

Use this script:

• For all standard release workflows
• This is the primary script users should run

Troubleshooting

Error: No releasable commits found

Cause: All commits since last release are non-releasable types (docs, style, refactor, test, build, ci, chore).

Solution:

• Check commits with: git log $(git describe --tags --abbrev=0)..HEAD --oneline
• Verify commit messages follow Conventional Emoji Commits format
• Need at least one: feat, fix, perf, or BREAKING CHANGE

Error: Working tree is dirty

Cause: Uncommitted changes in working directory.

Solution:

# Check status
git status

# Commit or stash changes
git add .
git commit -m "🔧 build: prepare for release"

# Or stash
git stash

Error: Not on main branch

Cause: Currently on a different branch.

Solution:

# Switch to main
git checkout main
git pull

# Or specify different branch
./scripts/bump_release.sh --branch develop

Error: git-cliff not found

Cause: git-cliff is not installed.

Solution:

cargo install git-cliff

Error: gh not authenticated

Cause: GitHub CLI is not authenticated.

Solution:

gh auth login

Error: Cargo validation failed

Cause: Cargo.toml changes caused compilation errors.

Solution:

• Check cargo check output for errors
• Fix Cargo.toml syntax or dependency issues
• Ensure version format is valid (X.Y.Z)

Error: Failed to push to remote

Cause: No permission or network issues.

Solution:

# Check remote
git remote -v

# Try manual push
git push
git push origin v1.2.3

# Check GitHub permissions
gh auth status

Version didn't change

Cause: No version bump needed (all commits are non-releasable).

Solution:

• This is expected behavior
• Check commits with --dry-run to see analysis
• Add feature or fix commits if a release is needed

Advanced Usage

Custom Changelog Configuration

Create .cliff.toml or cliff.toml at project root to customize changelog formatting.

Example configuration:

[changelog]
header = "# Changelog\n\n"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group | upper_first }}
{% for commit in commits %}
- {{ commit.message | split(pat="\n") | first | trim }}\
{% if commit.github.pr_number %} ([#{{ commit.github.pr_number }}]({{ commit.github.pr_url }})){% endif %}\
{% if commit.breaking %} **BREAKING**{% endif %}
{% endfor %}
{% endfor %}
"""

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
  { message = "^feat", group = "Features" },
  { message = "^fix", group = "Bug Fixes" },
  { message = "^perf", group = "Performance" },
  { message = "^doc", group = "Documentation" },
  { message = "^refactor", group = "Refactoring" },
  { message = "^test", group = "Testing" },
  { message = "^build", group = "Build" },
  { message = ".*: add", group = "Features" },
  { message = ".*: support", group = "Features" },
  { message = ".*: remove", group = "Removal" },
  { body = ".*BREAKING[- ]CHANGE.*", group = "BREAKING CHANGES" },
]

CI/CD Integration

Execute releases automatically on push to main:

GitHub Actions example:

name: Release
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for tags

      - name: Install git-cliff
        run: cargo install git-cliff

      - name: Fetch skill
        run: |
          # Download skill from repository or artifact

      - name: Execute release
        run: |
          cd skill-directory
          ./scripts/bump_release.sh --skip-checks
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Manual Version Override

Override automatic version determination:

# 1. Manually set version
./scripts/bump_version.py 2.0.0

# 2. Validate
cargo check

# 3. Generate changelog for specific version
git-cliff --tag v2.0.0 > CHANGELOG_ENTRY.md

# 4. Update CHANGELOG.md manually

# 5. Create commit and tag
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "🔖 release: bump version to v2.0.0"
git tag -a v2.0.0 -m "Release v2.0.0"

# 6. Push
git push && git push origin v2.0.0

# 7. Create GitHub release
gh release create v2.0.0 --notes-file CHANGELOG_ENTRY.md

Monorepo / Workspace Handling

For Rust workspaces with multiple crates:

Single versioning (recommended):

• Keep all workspace members at the same version
• bump_version.py updates all Cargo.toml files
• Use --workspace-deps flag to update dependency references

Independent versioning:

• Release each crate separately
• Specify --root to target specific crate directory
• Manage tags with prefixes (e.g., sdk-v1.0.0, cli-v1.0.0)

Error Recovery

Undo Last Release (Before Push)

If release was created locally but not pushed:

# Delete tag
git tag -d v1.2.3

# Reset to before release commit
git reset --hard HEAD~1

# Changes are undone

Undo Last Release (After Push)

If release was pushed to GitHub:

# 1. Delete GitHub release
gh release delete v1.2.3 --yes

# 2. Delete remote tag
git push origin :refs/tags/v1.2.3

# 3. Delete local tag
git tag -d v1.2.3

# 4. Revert release commit
git revert HEAD
git push

# 5. Fix issues and create new release

Fix Changelog After Release

If changelog needs corrections after release:

# 1. Edit CHANGELOG.md manually

# 2. Amend release commit (if not pushed yet)
git add CHANGELOG.md
git commit --amend --no-edit

# 3. Or create new commit (if already pushed)
git add CHANGELOG.md
git commit -m "📚 docs: fix changelog formatting"
git push

# 4. Update GitHub release notes
gh release edit v1.2.3 --notes "$(git-cliff --latest)"

Best Practices

Before Each Release

1. Review commits:

   git log $(git describe --tags --abbrev=0)..HEAD --oneline
   

2. Run dry-run first:

   ./scripts/bump_release.sh --dry-run
   

3. Verify tests pass:

   cargo test --workspace
   

4. Check for uncommitted changes:

   git status
   

Commit Message Quality

• Write clear, descriptive commit messages
• Follow Conventional Emoji Commits format strictly
• Include scope when helpful: feat(auth): vs feat:
• Document breaking changes thoroughly in commit body
• Reference issue numbers: Fixes #42

Changelog Maintenance

• Review generated changelog before finalizing
• Add migration guides for breaking changes
• Include links to documentation
• Credit contributors when appropriate

Version Strategy

• Use MAJOR for breaking changes (strict)
• Use MINOR for new features
• Use PATCH for bug fixes and performance
• Use prerelease suffixes for betas: 1.0.0-beta.1
• Never skip versions or go backwards

Summary

This skill automates the entire Rust project release workflow using Conventional Emoji Commits for version determination. Execute the main script (bump_release.sh) to automatically analyze commits, bump versions, generate changelogs, and create GitHub releases. Use --dry-run to preview changes, and individual scripts for specialized tasks. Ensure all prerequisites are met and follow best practices for smooth releases.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.