Skip to content

Version Management

Complete guide to version management in the Code Graph Knowledge System.

Overview

We use Semantic Versioning (SemVer) with automated tooling to ensure consistency across all version references.

Version Format: MAJOR.MINOR.PATCH (e.g., 0.7.0, 1.2.3)

Version Rules: - MAJOR (x.0.0): Breaking changes, major architecture updates - MINOR (0.x.0): New features, backward compatible - PATCH (0.0.x): Bug fixes, small improvements

Tools

bump-my-version

We use bump-my-version (formerly bump2version) to automate version updates.

Installation: 

pip install bump-my-version

Configuration: .bumpversion.toml

Version Sources

Single Source of Truth: pyproject.toml

The authoritative version is stored in pyproject.toml:

[project]
version = "0.7.0"

Synchronized Files

These files are automatically updated by bump-my-version:

  1. pyproject.toml - Package version
  2. src/__version__.py - Runtime version access
  3. docs/changelog.md - Version history
  4. Git tag - v0.7.0

Bumping Versions

# Patch version (0.7.0 → 0.7.1)
./scripts/bump-version.sh patch

# Minor version (0.7.1 → 0.8.0)
./scripts/bump-version.sh minor

# Major version (0.8.0 → 1.0.0)
./scripts/bump-version.sh major

# Dry run to preview changes
./scripts/bump-version.sh minor --dry-run

What the script does: 1. ✅ Validates no uncommitted changes 2. ✅ Shows current and new version 3. ✅ Asks for confirmation 4. ✅ Updates all version files 5. ✅ Creates git commit 6. ✅ Creates git tag 7. ✅ Shows next steps

Method 2: Manual bump-my-version

# Bump patch version
bump-my-version bump patch

# Bump minor version
bump-my-version bump minor

# Bump major version
bump-my-version bump major

# Dry run
bump-my-version bump minor --dry-run

# Show current configuration
bump-my-version show-bump

If you need to bump manually:

# 1. Update version in all files
vim pyproject.toml          # version = "0.8.0"
vim src/__version__.py      # __version__ = "0.8.0"
vim docs/changelog.md       # Add new version entry

# 2. Commit changes
git add pyproject.toml src/__version__.py docs/changelog.md
git commit -m "chore: bump version to 0.8.0"

# 3. Create tag
git tag -a v0.8.0 -m "Release v0.8.0"

# 4. Push
git push origin main
git push origin v0.8.0

Release Workflow

Standard Release

# 1. Ensure you're on main and up to date
git checkout main
git pull origin main

# 2. Update changelog with release notes
vim docs/changelog.md
# Add release notes under [Unreleased] section

# 3. Commit changelog updates
git add docs/changelog.md
git commit -m "docs: update changelog for v0.8.0"
git push origin main

# 4. Bump version (creates commit + tag)
./scripts/bump-version.sh minor

# 5. Push changes and tag
git push origin main
git push origin v0.8.0

# 6. GitHub Actions automatically:
#    - Builds Docker images (minimal, standard, full)
#    - Pushes to Docker Hub with version tags
#    - Creates GitHub Release

Hotfix Release

For urgent bug fixes on production:

# 1. Create hotfix branch from tag
git checkout -b hotfix/v0.7.1 v0.7.0

# 2. Fix the bug
git add <files>
git commit -m "fix: critical bug description"

# 3. Bump patch version
./scripts/bump-version.sh patch

# 4. Push and create PR
git push origin hotfix/v0.7.1

# 5. After merge, tag is already created
git checkout main
git pull origin main
git push origin v0.7.1

Docker Image Versioning

When you push a tag v0.7.0, GitHub Actions creates these Docker images:

Full Version Tags

royisme/codebase-rag:0.7.0-minimal
royisme/codebase-rag:0.7.0-standard
royisme/codebase-rag:0.7.0-full

Minor Version Tags (auto-updated for patches)

royisme/codebase-rag:0.7-minimal
royisme/codebase-rag:0.7-standard
royisme/codebase-rag:0.7-full

Latest Tags (from main branch)

royisme/codebase-rag:minimal
royisme/codebase-rag:standard
royisme/codebase-rag:full
royisme/codebase-rag:latest  # Points to full

Development Tags (main branch, no tag)

royisme/codebase-rag:dev-minimal
royisme/codebase-rag:dev-standard
royisme/codebase-rag:dev-full

Runtime Version Access

Python Code

from src.__version__ import __version__, get_features

# Get version string
print(f"Version: {__version__}")  # "0.7.0"

# Get version tuple
from src.__version__ import __version_info
print(__version_info__)  # (0, 7, 0)

# Check features
features = get_features()
if features["auto_extraction"]:
    print("Auto-extraction available")

API Endpoint

# Health endpoint includes version
curl http://localhost:8000/api/v1/health

{
  "status": "healthy",
  "version": "0.7.0",
  "deployment_mode": "full"
}

MCP Tool

{
  "tool": "system_info",
  "response": {
    "version": "0.7.0",
    "features": ["code_graph", "memory_store", "auto_extraction"]
  }
}

Version Validation in CI/CD

GitHub Actions validates version consistency:

- name: Validate Version Consistency
  run: |
    # Get version from pyproject.toml
    PROJECT_VERSION=$(grep '^version = ' pyproject.toml | cut -d'"' -f2)

    # Get version from __version__.py
    VERSION_PY=$(grep '__version__ = ' src/__version__.py | cut -d'"' -f2)

    # Get tag version (if tagged)
    if [[ $GITHUB_REF == refs/tags/* ]]; then
      TAG_VERSION=${GITHUB_REF#refs/tags/v}
      if [[ "$PROJECT_VERSION" != "$TAG_VERSION" ]]; then
        echo "Error: Version mismatch!"
        echo "pyproject.toml: $PROJECT_VERSION"
        echo "Git tag: $TAG_VERSION"
        exit 1
      fi
    fi

    # Validate Python version file
    if [[ "$PROJECT_VERSION" != "$VERSION_PY" ]]; then
      echo "Error: Version mismatch!"
      echo "pyproject.toml: $PROJECT_VERSION"
      echo "__version__.py: $VERSION_PY"
      exit 1
    fi

    echo "✓ All versions consistent: $PROJECT_VERSION"

Changelog Format

Follow this format in docs/changelog.md:

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features go here

### Changed
- Changes in existing functionality

### Fixed
- Bug fixes

## [0.8.0] - 2025-01-20

### Added
- Feature A
- Feature B

### Changed
- Updated dependency X

### Fixed
- Bug #123

## [0.7.0] - 2025-01-15

...

Troubleshooting

Version mismatch error

# If versions are out of sync, manually fix:
vim pyproject.toml src/__version__.py

# Then commit
git add pyproject.toml src/__version__.py
git commit -m "fix: synchronize version numbers"

Tag already exists

# Delete local tag
git tag -d v0.7.0

# Delete remote tag
git push origin :refs/tags/v0.7.0

# Recreate tag
git tag -a v0.7.0 -m "Release v0.7.0"
git push origin v0.7.0

Uncommitted changes

# Stash changes
git stash

# Bump version
./scripts/bump-version.sh patch

# Restore changes
git stash pop

Best Practices

  1. Always bump on main branch - Never bump version on feature branches
  2. Update changelog first - Write release notes before bumping
  3. Use dry-run - Preview changes with --dry-run flag
  4. Test before release - Ensure all tests pass before creating tag
  5. Semantic meaning - Follow SemVer strictly for predictability
  6. Document breaking changes - Clearly mark breaking changes in changelog

Quick Reference

Task Command
Bump patch ./scripts/bump-version.sh patch
Bump minor ./scripts/bump-version.sh minor
Bump major ./scripts/bump-version.sh major
Dry run ./scripts/bump-version.sh minor --dry-run
Show current bump-my-version show-bump
Manual bump bump-my-version bump patch
Push release git push origin main && git push origin v0.x.0

Resources