Version Bump & Tag Management — Development Guide

You are an expert on semantic versioning and release management. Use this knowledge when bumping versions, creating tags, or troubleshooting release pipelines.

What It Is

A systematic approach to version management that keeps all project files in sync, creates proper git tags, and triggers CI/CD release pipelines.

This project’s scripts:

• ./app/scripts/bump-version.sh — Version bumping
• ./app/scripts/redeploy.sh — Re-trigger failed releases

Quick Reference (This Project)

# Bump and release
./app/scripts/bump-version.sh patch    # 0.1.0 → 0.1.1
./app/scripts/bump-version.sh minor    # 0.1.0 → 0.2.0
./app/scripts/bump-version.sh major    # 0.1.0 → 1.0.0
git push && git push --tags

# Other options
./app/scripts/bump-version.sh --set 2.0.0    # Explicit version
./app/scripts/bump-version.sh patch --dry-run # Preview changes
./app/scripts/bump-version.sh patch --no-git  # Skip commit/tag

# Re-deploy failed release
./app/scripts/redeploy.sh              # Current version
./app/scripts/redeploy.sh v0.1.5       # Specific version

Semantic Versioning

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes (backward compatible)
  │     └──────── New features (backward compatible)
  └────────────── Breaking changes (incompatible API)

Pre-release Versions

1.0.0-alpha.1    # Early development
1.0.0-beta.1     # Feature complete, testing
1.0.0-rc.1       # Release candidate

Version Files by Project Type

Tauri Applications (This Project)

Node.js Projects

Rust Projects

Pre-Push Validation

Always validate before releasing:

# Quick check
git status --porcelain | grep -q . && echo "UNCOMMITTED CHANGES" && exit 1
git fetch origin
git log @{u}..HEAD --oneline | grep -q . && echo "UNPUSHED COMMITS" && exit 1
echo "Ready to release"

Full Validation Function

validate_ready_to_release() {
    # Check for uncommitted changes
    if [[ -n "$(git status --porcelain)" ]]; then
        echo "ERROR: Uncommitted changes"
        git status --short
        return 1
    fi

    # Check for unpushed commits
    git fetch origin --quiet
    local AHEAD=$(git log @{u}..HEAD --oneline 2>/dev/null | wc -l | tr -d ' ')
    if [[ "$AHEAD" -gt 0 ]]; then
        echo "ERROR: $AHEAD unpushed commit(s)"
        return 1
    fi

    echo "Ready to release"
    return 0
}

Git Tag Operations

Creating Tags

# Annotated tag (recommended)
git tag -a v1.0.0 -m "Release v1.0.0"

# With release notes
git tag -a v1.0.0 -m "Release v1.0.0

- Feature: Added user auth
- Fix: Memory leak resolved
- Chore: Updated deps"

Pushing Tags

git push origin v1.0.0      # Single tag
git push --tags             # All tags
git push && git push --tags # Commits + tags

Listing Tags

git tag -l                  # All tags
git tag -l "v1.*"           # Pattern match
git show v1.0.0             # Tag details
git describe --tags --abbrev=0  # Latest tag

Deleting Tags

git tag -d v1.0.0                    # Local
git push origin :refs/tags/v1.0.0    # Remote

Recreating Tags (Re-release)

git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

Redeployment

When a release fails mid-build, use redeployment to re-trigger without version change.

What Redeploy Does

1. Deletes tag locally (if exists)
2. Deletes tag on remote (if exists)
3. Recreates annotated tag at HEAD
4. Pushes new tag
5. CI/CD workflow re-triggers

Manual Redeployment

VERSION="v0.1.5"

# Validate first
git status --porcelain | grep -q . && echo "Uncommitted changes!" && exit 1

# Delete and recreate
git tag -d "$VERSION" 2>/dev/null || true
git push origin ":refs/tags/$VERSION" 2>/dev/null || true
git tag -a "$VERSION" -m "Release $VERSION"
git push origin "refs/tags/$VERSION"

When to Redeploy

• CI/CD workflow failed mid-build
• Build artifacts corrupted
• Code signing failed
• Secrets/environment updated
• Artifact upload failed

Complete Release Workflow

Manual Steps

# 1. Ensure clean state
git status  # No uncommitted changes

# 2. Get current version
CURRENT=$(jq -r '.version' package.json)

# 3. Calculate new version
IFS='.' read -r major minor patch <<< "$CURRENT"
NEW="${major}.${minor}.$((patch + 1))"

# 4. Update all version files
# (Use bump script or edit manually)

# 5. Commit
git add -A
git commit -m "chore: bump version to v${NEW}"

# 6. Tag
git tag -a "v${NEW}" -m "Release v${NEW}"

# 7. Push
git push && git push --tags

Using This Project’s Script

./app/scripts/bump-version.sh patch
git push && git push --tags

The script handles steps 2-6 automatically.

Version Comparison in Bash

VERSION="1.2.3"
IFS='.' read -r MAJOR MINOR PATCH <<< "$VERSION"

# Patch bump
PATCH=$((PATCH + 1))
NEW="${MAJOR}.${MINOR}.${PATCH}"  # 1.2.4

# Minor bump
MINOR=$((MINOR + 1)); PATCH=0
NEW="${MAJOR}.${MINOR}.${PATCH}"  # 1.3.0

# Major bump
MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0
NEW="${MAJOR}.${MINOR}.${PATCH}"  # 2.0.0

Useful Commands

Common Gotchas

1. Tag format must match workflow trigger — If workflow triggers on v*, use v0.1.0 not 0.1.0.
2. Push commits before tags — Tags reference commits; the commit must exist on remote first.
3. Version files must all match — Mismatch causes build failures. Use the bump script.
4. Cargo.lock needs regeneration — After editing Cargo.toml, run cargo update -p <pkg>.
5. Don’t amend tagged commits — Creates divergent history. Create new commit + tag instead.
6. Annotated tags for releases — Lightweight tags (git tag v1.0.0) lack metadata. Use -a.
7. Tag deletion is not instant — GitHub may cache tags briefly. Wait a moment before recreating.
8. CI runs against tagged commit — Ensure all changes are committed before tagging.
9. Pre-release versions sort correctly — 1.0.0-alpha.1 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0
10. Conventional commits for bumps — Use chore: bump version to vX.Y.Z or release: vX.Y.Z.