feat: add commitizen for automated version management

[bokelley]

Summary

Implements commitizen-based version management for automated versioning and changelog generation using pure Python (no Node.js required).

What's Changed

Core Implementation

• ✅ Add commitizen>=3.29.0 dependency to pyproject.toml
• ✅ Configure commitizen in pyproject.toml (PEP 621, semver, incremental changelog)
• ✅ Create commitizen-check.yml CI workflow to enforce conventional commits
• ✅ Create release.yml CI workflow for automated version bumps on merge to main
• ✅ Add .cz-config.md with detailed commit guidelines and examples

Documentation

• ✅ Comprehensive guide in README.md with conventional commit format
• ✅ Examples for all commit types (feat, fix, docs, test, chore, etc.)
• ✅ Breaking change syntax examples
• ✅ Automated release workflow explained

Cleanup

• ✅ Remove changesets (Node.js) implementation
• ✅ Remove package.json, package-lock.json, node_modules
• ✅ Remove .changeset/ directory
• ✅ Remove scripts/sync_version.py (no longer needed)

How It Works

For Contributors

Write commits following Conventional Commits format:

# Feature (minor bump: 0.1.0 → 0.2.0)
git commit -m "feat: add OAuth authentication support"
git commit -m "feat(gam): add support for video creatives"

# Bug fix (patch bump: 0.1.0 → 0.1.1)
git commit -m "fix: correct schema validation"
git commit -m "fix(auth): prevent token race condition"

# Breaking change (major bump: 0.1.0 → 1.0.0)
git commit -m "feat!: redesign API response format

BREAKING CHANGE: Response format changed from {data} to {result}"

# No version bump
git commit -m "docs: update README"
git commit -m "test: add integration tests"
git commit -m "chore: update dependencies"

Optional: Use interactive commit helper:

uv run cz commit

For Maintainers

When commits are merged to main:

1. CI analyzes commits: Looks for feat, fix, BREAKING CHANGE commits since last tag
2. Determines bump type: major, minor, or patch based on commit types
3. Bumps version: Updates pyproject.toml automatically
4. Updates CHANGELOG: Generates changelog from commit messages
5. Creates tag: Git tag (e.g., v0.2.0)
6. Creates release: GitHub release with changelog
7. Pushes to main: All changes committed back

Zero manual steps - it's fully automated!

CI Workflows

commitizen-check.yml

• Runs on every PR to main
• Validates all commits follow conventional commit format
• Fails if any commit doesn't match pattern
• Uses: cz check --rev-range origin/main..HEAD

release.yml

• Runs on every push to main
• Checks if version bump is needed (looks for feat/fix/BREAKING commits)
• Runs cz bump --yes --changelog if needed
• Creates git tag and GitHub release
• Pushes changes back to main

Commit Types & Version Bumps

Type	Description	Version Bump	Example
feat	New feature	minor (0.1.0 → 0.2.0)	feat: add OAuth support
fix	Bug fix	patch (0.1.0 → 0.1.1)	fix: correct validation
perf	Performance	patch (0.1.0 → 0.1.1)	perf: optimize query
BREAKING	Breaking change	major (0.1.0 → 1.0.0)	feat!: redesign API
docs	Documentation	none	docs: update README
test	Tests	none	test: add unit tests
chore	Tooling	none	chore: update deps
refactor	Refactoring	none	refactor: simplify logic

Benefits vs Changesets

✅ Pure Python: No Node.js/npm required
✅ Fully automated: Version bumps from commit messages
✅ Zero extra files: No changeset markdown files to manage
✅ Standard format: Conventional Commits is widely used
✅ Enforced by CI: Can't merge PRs with bad commit messages
✅ Less overhead: One commit command, not two steps

Testing

• Commitizen installed and configured
• cz version shows correct project version (0.1.0)
• Configuration in pyproject.toml validated
• Documentation complete with examples
• CI workflows created and tested

Example Workflow

# 1. Make changes
git add .

# 2. Commit with conventional format
git commit -m "feat: add webhook support"

# 3. Push to PR
git push origin feature-branch

# 4. CI validates commit format ✅

# 5. Merge to main

# 6. CI automatically:
#    - Bumps version to 0.2.0
#    - Updates CHANGELOG.md
#    - Creates tag v0.2.0
#    - Creates GitHub release
#    - Pushes to main

Resources

• Commitizen Documentation
• Conventional Commits Specification
• Project Commit Guidelines

🤖 Generated with Claude Code