Add semantic versioning validation and changelog sync checks

[johnsosoka]

Problem

Current release process lacks automated validation for:

• Version format compliance with semantic versioning (semver)
• CHANGELOG.md entries for new versions
• Git tag alignment with package version

This can lead to:

• Non-standard version formats (e.g., 0.2.0-alpha vs 0.2.0)
• Releases without changelog documentation
• Git tags that don't match published versions

Proposed Solution

Implement comprehensive version validation checks in CI pipeline.

Validation Checks

1. Semantic Versioning Format

import re
import sys

version = "0.2.0"  # from pyproject.toml
semver_pattern = r'^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'

if not re.match(semver_pattern, version):
    print(f"ERROR: Version '{version}' does not follow semantic versioning")
    sys.exit(1)

2. CHANGELOG.md Entry Validation

VERSION=$(grep -E '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')

if ! grep -q "## \[$VERSION\]" CHANGELOG.md; then
  echo "ERROR: CHANGELOG.md missing entry for version $VERSION"
  exit 1
fi

3. Git Tag Validation (on tag push)

# .github/workflows/publish.yml
- name: Validate tag matches version
  run: |
    TAG_VERSION="${GITHUB_REF#refs/tags/v}"
    PKG_VERSION=$(grep -E '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
    
    if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
      echo "ERROR: Git tag (v$TAG_VERSION) doesn't match package version ($PKG_VERSION)"
      exit 1
    fi

4. Version Bump Detection

• Ensure new version > previous version
• Detect if version was actually changed (prevent re-releases)

Implementation Approach

Phase 1: Basic Validation

• Add semver format check to CI
• Add CHANGELOG validation to CI
• Document version bump process

Phase 2: Enhanced Tooling

• Create scripts/bump_version.py helper:

  python scripts/bump_version.py --patch  # 0.2.0 -> 0.2.1
  python scripts/bump_version.py --minor  # 0.2.0 -> 0.3.0
  python scripts/bump_version.py --major  # 0.2.0 -> 1.0.0

• Automatically updates: pyproject.toml, __init__.py, CHANGELOG.md
• Creates git tag with proper format

Phase 3: Release Automation

• GitHub Actions workflow to automate version bumps
• PR-based version bump process
• Automatic changelog generation

Acceptance Criteria

• CI validates semver format on all commits
• CI validates CHANGELOG.md has entry for current version
• Publish workflow validates git tag matches package version
• Documentation in CONTRIBUTING.md for version bump process
• Consider: Version bump helper script (optional)

Related Issues

• Enforce version consistency between pyproject.toml and __init__.py #6 - Version sync validation (foundational requirement)

References

• Semantic Versioning 2.0.0
• Keep a Changelog