🤖 Automated Version Bump System¶

This system automatically analyzes commits pushed to the main branch and performs appropriate version bumps with automated releases.

🚀 How It Works¶

1. Trigger Conditions¶

The automated version bump workflow triggers when:

Code is pushed to the main branch
The commit is not from GitHub Actions (prevents infinite loops)
Changes are made to significant files (excludes docs, workflows, etc.)

2. Commit Analysis¶

The system analyzes commit messages and file changes to determine the appropriate version bump:

Version Bump Rules¶

MAJOR (X.0.0): Breaking changes, major refactors
Commit messages: BREAKING CHANGE:, breaking:, major:
Significant changes to critical files (Gemfile, gemspec, configs)
MINOR (0.X.0): New features, enhancements
Commit messages: feat:, feature:, add:, new:
Addition of new layouts, includes, or major functionality
PATCH (0.0.X): Bug fixes, small improvements, maintenance
Commit messages: fix:, bug:, patch:, chore:, docs:
Small changes, documentation updates, dependency updates

3. Automated Process¶

When triggered, the system:

Analyzes all commits since the last version tag
Determines the highest appropriate version bump type
Generates changelog from commit history using conventional commit patterns
Updates version files (lib/jekyll-theme-zer0/version.rb, package.json)
Runs validation tests
Builds the gem package
Publishes to RubyGems.org
Creates GitHub release with automated release notes
Commits and pushes version bump changes

📋 Conventional Commit Format¶

To ensure proper automatic version bumping, use conventional commit messages:

# New features (MINOR bump)
git commit -m "feat: add responsive navigation menu"
git commit -m "feature: implement user authentication"

# Bug fixes (PATCH bump)
git commit -m "fix: resolve mobile layout issue"
git commit -m "bug: correct typo in footer"

# Breaking changes (MAJOR bump)
git commit -m "feat: redesign theme structure

BREAKING CHANGE: This updates the layout structure and requires manual migration"

# Maintenance (PATCH bump)
git commit -m "chore: update dependencies"
git commit -m "docs: improve installation instructions"

🛠️ Manual Override¶

If you need to manually trigger a version bump or override the automation:

# Manual version bump (bypasses automation)
./scripts/gem-publish.sh [patch|minor|major]

# Preview what automation would do
./scripts/analyze-commits.sh HEAD~5..HEAD

# Test the system
./scripts/test-auto-version.sh

🔧 Configuration¶

Workflow Configuration¶

The automation is configured in .github/workflows/auto-version-bump.yml:

Trigger paths: Excludes changelog, version files, docs, workflows
Safety checks: Prevents infinite loops from automated commits
Error handling: Comprehensive validation and rollback capabilities

Script Configuration¶

Key scripts and their purposes:

scripts/analyze-commits.sh: Analyzes commit history for version bump determination
scripts/gem-publish.sh: Enhanced publication script with automation support
scripts/test-auto-version.sh: Comprehensive test suite for the automation system

🚫 Preventing Automation¶

To skip automated version bumping on specific commits:

# Include [skip-release] in commit message
git commit -m "docs: update README [skip-release]"

# Or push to a different branch first
git push origin feature-branch
# Create PR instead of direct push to main

📊 Monitoring¶

The automation system provides:

Detailed logs in GitHub Actions workflow runs
Release notes automatically generated from commit history
Error notifications if the automation fails
Manual fallback procedures if intervention is needed

🧪 Testing¶

Test the automation system locally:

# Run full test suite
./scripts/test-auto-version.sh

# Test commit analysis only
./scripts/analyze-commits.sh HEAD~3..HEAD

# Test publication script with automation
./scripts/gem-publish.sh patch --dry-run --automated-release

🔍 Troubleshooting¶

Common Issues¶

Infinite Loop Protection
The workflow skips if commit author is 'github-actions'
Version bump commits include 'chore: bump version' pattern
No Version Bump Triggered
Check commit messages follow conventional format
Verify changes aren't in excluded paths
Review workflow conditions and filters
Publication Failures
Validate RubyGems credentials in repository secrets
Check gem specification and dependencies
Review build logs for detailed error messages
Manual Recovery

# If automation fails, recover manually:
git tag -d v[version]  # Remove failed tag
./scripts/gem-publish.sh [type] --skip-publish  # Test locally
./scripts/gem-publish.sh [type]  # Full release

🎯 Best Practices¶

Use Conventional Commits: Ensures proper categorization and version bumping
Small, Focused Commits: Makes analysis more accurate and changelogs cleaner
Test Before Pushing: Use --dry-run options to preview changes
Monitor Automation: Review automated releases for accuracy
Manual Override When Needed: Don't hesitate to use manual processes for complex releases

This automated system follows semantic versioning and conventional commit standards to provide reliable, hands-off release management while maintaining full manual control when needed.