feat: add commitizen for automated version management

.cz-config.md

@@ -0,0 +1,120 @@
+# Commitizen Configuration
+
+This project uses Commitizen for automated version management and changelog generation.
+
+## Commit Message Format
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## Commit Types
+
+| 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 error` |
+| `docs` | Documentation | none | `docs: update README` |
+| `test` | Tests | none | `test: add unit tests` |
+| `chore` | Tooling/build | none | `chore: update dependencies` |
+| `refactor` | Code refactoring | none | `refactor: simplify auth logic` |
+| `perf` | Performance | patch | `perf: optimize query` |
+| `style` | Code style | none | `style: format with black` |
+| `ci` | CI/CD changes | none | `ci: add test workflow` |
+| `build` | Build system | none | `build: update docker config` |
+
+## Breaking Changes
+
+For breaking changes, use `!` after type or add `BREAKING CHANGE:` in footer:
+
+```bash
+# Method 1: Using !
+git commit -m "feat!: redesign API format"
+
+# Method 2: Using footer
+git commit -m "feat: redesign API format
+
+BREAKING CHANGE: Response format changed from {data} to {result}"
+```
+
+Breaking changes trigger a major version bump (0.1.0 → 1.0.0).
+
+## Scope (Optional)
+
+Use scope to specify what part of codebase is affected:
+
+```bash
+git commit -m "feat(gam): add video creative support"
+git commit -m "fix(auth): prevent token race condition"
+git commit -m "docs(api): update MCP tool documentation"
+```
+
+Common scopes: `gam`, `auth`, `api`, `mcp`, `a2a`, `admin`, `db`
+
+## Commands
+
+```bash
+# Interactive commit (recommended for beginners)
+uv run cz commit
+
+# Check commit message format
+uv run cz check
+
+# Check all commits in a range
+uv run cz check --rev-range main..HEAD
+
+# Bump version (done automatically by CI)
+uv run cz bump
+
+# Show current version
+uv run cz version
+```
+
+## CI Automation
+
+- **On PR**: `commitizen-check.yml` validates all commits follow format
+- **On merge to main**: `release.yml` automatically bumps version and updates changelog
+- **No manual steps**: Just write good commit messages!
+
+## Examples
+
+### Good Commits ✅
+
+```bash
+feat: add webhook support for media buy events
+fix: correct timezone handling in campaign scheduling
+docs: add deployment guide for Kubernetes
+test: add integration tests for A2A protocol
+chore: update commitizen to v3.29.0
+refactor: simplify GAM adapter error handling
+perf: optimize database query for large tenants
+```
+
+### Bad Commits ❌
+
+```bash
+update code                    # ❌ No type
+feat add feature              # ❌ Missing colon
+FIX: bug                      # ❌ Type should be lowercase
+feat(GAM): new feature        # ❌ Scope should be lowercase
+```
+
+## Tips
+
+1. **Be specific**: "feat: add OAuth" is better than "feat: update auth"
+2. **Use imperative mood**: "add feature" not "adds feature" or "added feature"
+3. **Keep subject under 72 characters**
+4. **Use body for details**: Subject is a summary, body explains why
+5. **Reference issues**: "Closes #123" in footer to auto-close issues
+
+## Resources
+
+- [Conventional Commits Specification](https://www.conventionalcommits.org/)
+- [Commitizen Documentation](https://commitizen-tools.github.io/commitizen/)
+- [Angular Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit) (similar format)

.github/workflows/commitizen-check.yml

@@ -0,0 +1,36 @@
+name: Commitizen Check
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  commitizen-check:
+    name: Check Conventional Commits
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/0.4.18/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv sync
+
+      - name: Check commits follow conventional commit format
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          # Check all commits in this PR
+          uv run cz check --rev-range origin/main..HEAD

.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Bump Version and Create Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/0.4.18/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+      - name: Install dependencies
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          uv sync
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Check if version bump is needed
+        id: check_bump
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          # Check if there are any commits since last tag that warrant a version bump
+          LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.1.0")
+          echo "Last tag: $LAST_TAG"
+
+          # Check if there are feat/fix/BREAKING commits since last tag
+          if git log $LAST_TAG..HEAD --oneline | grep -qE '^[a-f0-9]+ (feat|fix|perf|refactor|BREAKING CHANGE)'; then
+            echo "needs_bump=true" >> $GITHUB_OUTPUT
+            echo "✅ Found commits that need version bump"
+          else
+            echo "needs_bump=false" >> $GITHUB_OUTPUT
+            echo "ℹ️  No version bump needed (only chore/docs/test commits)"
+          fi
+
+      - name: Bump version and update changelog
+        if: steps.check_bump.outputs.needs_bump == 'true'
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+
+          # Bump version (automatically determines bump type from commits)
+          uv run cz bump --yes --changelog
+
+          # Get the new version
+          NEW_VERSION=$(uv run cz version -p)
+          echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
+
+          echo "✅ Bumped to version $NEW_VERSION"
+
+      - name: Push changes
+        if: steps.check_bump.outputs.needs_bump == 'true'
+        run: |
+          git push origin main --tags
+          echo "✅ Pushed version bump and tags to main"
+
+      - name: Create GitHub Release
+        if: steps.check_bump.outputs.needs_bump == 'true'
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ env.NEW_VERSION }}
+          release_name: Release v${{ env.NEW_VERSION }}
+          body: |
+            ## Changes
+
+            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
+          draft: false
+          prerelease: false
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.check_bump.outputs.needs_bump }}" == "true" ]; then
+            echo "✅ Version bumped to ${{ env.NEW_VERSION }}"
+            echo "✅ Changelog updated"
+            echo "✅ Git tag created and pushed"
+            echo "✅ GitHub release created"
+          else
+            echo "ℹ️  No version bump needed - no feat/fix/BREAKING commits found"
+          fi

CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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
+- Changeset system for automated version management
+- CI workflows to enforce changeset requirements on PRs
+- Automated version bump PR creation when changesets are merged
+
+## [0.1.0] - 2025-01-29
+
+Initial release of the AdCP Sales Agent reference implementation.
+
+### Added
+- MCP server implementation with AdCP v2.3 support
+- A2A (Agent-to-Agent) protocol support
+- Multi-tenant architecture with PostgreSQL
+- Google Ad Manager (GAM) adapter
+- Mock ad server adapter for testing
+- Admin UI with Google OAuth authentication
+- Comprehensive testing backend with dry-run support
+- Real-time activity dashboard with SSE
+- Workflow management system
+- Creative management and approval workflows
+- Audit logging
+- Docker deployment support
+- Extensive documentation
+
+[Unreleased]: https://github.com/adcontextprotocol/salesagent/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/adcontextprotocol/salesagent/releases/tag/v0.1.0

README.md

@@ -236,6 +236,80 @@ We welcome contributions! Please see our [Development Guide](docs/DEVELOPMENT.md
 - Code style guidelines
 - Creating pull requests
 
+### Commitizen for Version Management
+
+This project uses [Commitizen](https://commitizen-tools.github.io/commitizen/) for automated version management and changelog generation.
+
+**Commit Message Format:**
+
+All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature (triggers minor version bump: 0.1.0 → 0.2.0)
+- `fix`: Bug fix (triggers patch version bump: 0.1.0 → 0.1.1)
+- `docs`: Documentation changes (no version bump)
+- `test`: Test changes (no version bump)
+- `chore`: Build/tooling changes (no version bump)
+- `refactor`: Code refactoring (no version bump)
+- `perf`: Performance improvements (triggers patch bump)
+- `BREAKING CHANGE`: Breaking change (triggers major version bump: 0.1.0 → 1.0.0)
+
+**Examples:**
+
+```bash
+# Feature (minor bump)
+git commit -m "feat: add OAuth authentication support"
+git commit -m "feat(gam): add support for video creatives"
+
+# Bug fix (patch bump)
+git commit -m "fix: correct schema validation for media buy"
+git commit -m "fix(auth): prevent token refresh race condition"
+
+# Breaking change (major bump)
+git commit -m "feat!: redesign API response format
+
+BREAKING CHANGE: Response format changed from {data} to {result}
+Clients must update to handle new format"
+
+# No version bump
+git commit -m "docs: update README with setup instructions"
+git commit -m "test: add integration tests for A2A protocol"
+git commit -m "chore: update pre-commit hooks"
+```
+
+**Using Commitizen CLI (Optional):**
+
+```bash
+# Interactive commit helper
+uv run cz commit
+
+# Check if commits follow format
+uv run cz check
+
+# Manually bump version (usually done by CI)
+uv run cz bump
+```
+
+**Automated Releases:**
+
+When commits are pushed to `main`:
+1. CI automatically analyzes commit messages
+2. Determines version bump type (major/minor/patch)
+3. Updates version in `pyproject.toml`
+4. Updates `CHANGELOG.md` with changes
+5. Creates git tag and GitHub release
+6. Pushes changes back to `main`
+
+No manual version bumps needed - it's all automated from your commit messages!
+
 ### Important: Database Access Patterns
 
 When contributing, please follow our standardized database patterns: