Skip to content

Version Management Guide

Semantic Versioning

MicroDC Worker follows Semantic Versioning 2.0.0:

MAJOR.MINOR.PATCH

Version Components

  • MAJOR (X.0.0): Incompatible API changes, breaking changes
  • MINOR (0.X.0): New functionality in a backward-compatible manner
  • PATCH (0.0.X): Backward-compatible bug fixes

Development Cycle

Pre-Release (0.x.x)

  • 0.1.x: Initial development and testing
  • 0.2.x: Beta testing and stabilization
  • 0.9.x: Release candidates

Production (1.x.x+)

  • 1.0.0: First production-ready release
  • 1.1.0: New features added
  • 1.1.1: Bug fixes
  • 2.0.0: Breaking changes

Current Version

Current version: 0.1.0 (Initial development)

Automatic Version Management

Quick Setup (One-Time)

Install the git hooks to enable automatic version bumping:

./tools/install-git-hooks.sh

That's it! Now every git commit will automatically increment the PATCH version.

How It Works

  1. Pre-Commit Hook: Runs before each commit
  2. Auto-Increment: Bumps PATCH version (0.1.0 → 0.1.1)
  3. Auto-Stage: Automatically stages the updated version file
  4. Commit: Your commit includes the version bump

Usage

Normal Commit (auto-increments):

git commit -m "Fix authentication bug"
# 🔄 Auto-incrementing version...
# ✅ Version bumped: 0.1.0 → 0.1.1

Bypass Hook (no version change):

git commit --no-verify -m "Update docs only"
# Skips version bump (use sparingly)

Manual Version Bump (without committing):

# Increment patch (0.1.0 → 0.1.1)
./tools/bump_version.py patch

# Increment minor (0.1.5 → 0.2.0)
./tools/bump_version.py minor

# Increment major (0.9.0 → 1.0.0)
./tools/bump_version.py major

When to Use Manual Bumps

  • MINOR: Use bump_version.py minor before adding significant features
  • MAJOR: Use bump_version.py major before breaking changes or 1.0.0 release
  • PATCH: Happens automatically on every commit (no action needed)

Documenting Version Changes

After committing, update docs/TODO.md under "Recently Completed":

- **Version 0.1.5** (2025-11-04)
  - Brief description of changes
  - List of key improvements or fixes

Version Increment Guidelines

When to Increment PATCH (0.1.X)

  • Bug fixes
  • Performance improvements
  • Documentation updates
  • Code refactoring (no API changes)
  • Security patches

Example: 0.1.0 → 0.1.1

When to Increment MINOR (0.X.0)

  • New features
  • New API endpoints
  • New configuration options
  • Deprecations (but still working)
  • Significant improvements

Example: 0.1.5 → 0.2.0

When to Increment MAJOR (X.0.0)

  • Breaking API changes
  • Removed deprecated features
  • Complete rewrites
  • Incompatible configuration changes
  • First production release: 0.9.x → 1.0.0

Example: 0.9.5 → 1.0.0 (first production release)

Version Tracking in Heartbeat

The worker automatically reports its version in every heartbeat:

{
  "worker_version": "0.1.0",
  "status": "idle",
  ...
}

This allows the server to:

  • Track deployed worker versions across the fleet
  • Identify workers that need updates
  • Debug version-specific issues
  • Enforce minimum version requirements

Server Compatibility

Worker version compatibility is defined in src/version.py:

__min_server_version__ = "0.0.1"  # Minimum compatible server version
__max_server_version__ = "999.999.999"  # Maximum compatible server version

Update these when:

  • Worker requires specific server features
  • Breaking changes affect server communication
  • API compatibility changes

Best Practices

1. Automatic Version Bumping

  • Enabled by default: After running install-git-hooks.sh, every commit auto-increments PATCH
  • No manual action needed: Version bumps happen automatically
  • Bypass when needed: Use --no-verify for docs-only commits

2. Manual Bumps for Significant Changes

  • Before new features: Run ./tools/bump_version.py minor
  • Before breaking changes: Run ./tools/bump_version.py major
  • Regular commits: Automatic PATCH bump (no action needed)

3. Document Changes

  • Update TODO.md with version and changes
  • Include file references (file.py:line)
  • Explain impact and benefits

4. Test Before Major Releases

  • Run full test suite
  • Test with target server version
  • Verify auto-update functionality

5. Git Tagging for Milestones

Tag major/minor releases:

git tag -a v0.2.0 -m "Beta testing release"
git push origin v0.2.0

6. Communication

  • Announce breaking changes
  • Provide migration guides for major versions
  • Document deprecations in advance

Version History

0.1.0 (2025-11-04)

  • Initial development version
  • Worker version tracking in heartbeat
  • Core functionality established
  • Pre-production development phase

Future Milestones

  • 0.2.0: Beta testing phase
  • 0.9.0: Release candidate
  • 1.0.0: First production release

Quick Reference

# ONE-TIME SETUP: Install git hooks for automatic version bumping
./tools/install-git-hooks.sh

# CHECK CURRENT VERSION
python -c "from src.version import __version__; print(__version__)"

# NORMAL WORKFLOW (automatic version bump)
git add .
git commit -m "Your commit message"
# → Version automatically increments: 0.1.0 → 0.1.1

# MANUAL VERSION BUMPS (before committing)
./tools/bump_version.py patch  # 0.1.0 → 0.1.1
./tools/bump_version.py minor  # 0.1.5 → 0.2.0
./tools/bump_version.py major  # 0.9.0 → 1.0.0

# BYPASS AUTO-INCREMENT (docs-only commits)
git commit --no-verify -m "Update documentation"

# TAG RELEASES (for major/minor milestones)
git tag -a v0.2.0 -m "Beta testing release"
git push origin v0.2.0

Notes

  • Automatic versioning: Every commit increments PATCH version (after running install-git-hooks.sh)
  • Single source of truth: src/version.py is the authoritative version
  • Heartbeat reporting: Version automatically reported to server every 30 seconds
  • Server tracking: Server can track fleet versions and enforce minimums
  • Auto-updater: Uses this version for compatibility checks