Automated Versioning and Release System

This document describes the automated semantic versioning and release system implemented for the bolster package.

Overview

The system automatically:

Analyzes merged PRs to determine appropriate version bump (major/minor/patch)
Bumps version using semantic versioning rules
Generates changelog from commit messages
Publishes to PyPI with trusted publishing
Creates GitHub releases with artifacts
Validates documentation completeness

How It Works

Trigger

Automatic: Every push to main branch (i.e., merged PR)
Manual: Workflow dispatch with version override

Version Determination

The system uses multiple signals to determine version bump:

1. Conventional Commits

feat: → minor version bump
fix: → patch version bump
BREAKING CHANGE or !: → major version bump
docs:, chore:, ci:, style:, test: → skip release

2. PR Labels (Override)

version:major → Force major bump
version:minor → Force minor bump
version:patch → Force patch bump
version:skip → Skip release entirely

3. Content Analysis

Breaking changes detected in PR description
New features vs bug fixes
Documentation-only changes

Workflow Steps

graph TD
    A[PR Merged to main] --> B[Analyze Changes]
    B --> C{Should Release?}
    C -->|No| D[Skip - No meaningful changes]
    C -->|Yes| E[Determine Version Bump]
    E --> F[Run Tests & Lint]
    F --> G[Bump Version]
    G --> H[Generate Changelog]
    H --> I[Build Package]
    I --> J[Publish to PyPI]
    J --> K[Create GitHub Release]
    K --> L[Trigger Docs Build]

Configuration Files

Core Workflows

File	Purpose
`.github/workflows/auto-release.yml`	Main automated release workflow
`.github/workflows/pr-labeler.yml`	Auto-label PRs for version control
`.github/workflows/docs-validation.yml`	Documentation completeness checking
`.github/pull_request_template.md`	PR template with versioning guidance

Supporting Files

File	Purpose
`CHANGELOG.md`	Auto-generated changelog
`pyproject.toml`	Version configuration with bump-my-version
`.github/workflows/release-env-setup.yml`	One-time environment setup

Usage Guide

For Developers

Creating a PR

Follow conventional commit format in PR title
Use the PR template to indicate change type
The system will auto-label your PR
Override version bump with labels if needed

Conventional Commit Examples

feat(nisra): add population statistics module     # → minor
fix(psni): correct date parsing in crime data     # → patch
feat!: restructure API with breaking changes      # → major
docs: update README with new examples            # → skip

PR Labels for Override

Add version:major for breaking changes
Add version:minor for new features
Add version:patch for bug fixes
Add version:skip for docs/maintenance only

For Maintainers

Manual Release

# Trigger manual release via GitHub UI
# Go to Actions > Automated Release > Run workflow
# Choose version bump type: auto, patch, minor, major

Emergency Fixes

# If automated release fails, manual fallback:
git checkout main
git pull
uv run pytest tests/ -v
uv run pre-commit run --all-files
uv run bump-my-version bump patch
git push origin main --tags

Quality Gates

Pre-Release Checks

✅ All tests pass (uv run pytest tests/ -v)
✅ Linting passes (uv run pre-commit run --all-files)
✅ Documentation completeness validated
✅ Version bump is appropriate for changes

Documentation Requirements

Public functions must have docstrings
New data source modules must be in README coverage table
Breaking changes must be documented
Examples must be provided for new features

Security

Trusted Publishing

Uses OpenID Connect (OIDC) tokens for PyPI publishing
No long-lived API keys stored in repository
GitHub environment protection for releases

Permissions

contents: write - For version bumps and tags
pull-requests: read - For analyzing PRs
id-token: write - For trusted publishing

Monitoring

Success Indicators

✅ Version bumped in pyproject.toml
✅ Git tag created (v1.2.3)
✅ Package published to PyPI
✅ GitHub release created
✅ Documentation updated

Failure Recovery

If the workflow fails:

Check GitHub Actions logs for specific error
Common issues:
- Tests failing → Fix tests first
- PyPI publishing → Check trusted publishing setup
- Version conflicts → Manual version bump needed
Manual recovery steps provided above

Best Practices

Commit Messages

# Good
feat(nisra): add tourism occupancy statistics
fix(dva): handle missing vehicle registration data
docs: update API examples for new tourism module

# Avoid
update stuff
fix bug
improvements

PR Descriptions

Clearly describe what changed
Mention breaking changes explicitly
Include usage examples for new features
Reference related issues/PRs

Version Strategy

Patch (1.0.0 → 1.0.1): Bug fixes, data corrections
Minor (1.0.0 → 1.1.0): New data sources, new features
Major (1.0.0 → 2.0.0): Breaking API changes

Troubleshooting

Common Issues

Problem	Solution
Release skipped unexpectedly	Check if PR only contains docs/CI changes
Wrong version bump	Add appropriate PR label to override
Tests fail during release	Fix tests, version bump will retry
PyPI publishing fails	Check trusted publishing configuration
Documentation validation fails	Add missing docstrings to public functions

Debug Commands

# Check current version
uv run python -c "import importlib.metadata; print(importlib.metadata.version('bolster'))"

# Test version bump locally (dry run)
uv run bump-my-version bump --dry-run patch

# Check what would be released
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%s"

AI Integration

Current AI Features

Documentation Validation (Optional)
- Automatic docstring completeness checking
- AI-generated documentation suggestions
- README coverage validation
- Requirement: Add ANTHROPIC_API_KEY to repository secrets
AI-Powered Code Review (Optional)
- Multi-agent security analysis
- Performance optimization suggestions
- Best practices review
- Requirement: Add ANTHROPIC_API_KEY or OPENAI_API_KEY to repository secrets
Release Documentation Validation (Optional)
- AI validation of documentation completeness before release
- Fallback: Basic validation if AI not configured

Enabling AI Features

Add one of these to your repository secrets:

# Preferred (more cost-effective)
ANTHROPIC_API_KEY=sk-ant-api03-...

# Alternative (not yet fully implemented)
OPENAI_API_KEY=sk-...

AI Feature Behavior

Fail-safe design: No AI features are required for core functionality
Graceful degradation: Falls back to basic validation if AI unavailable
Cost control: Uses efficient models (Claude Haiku) for most analysis
Transparent: All AI analysis is clearly marked and reviewable
Default-fail: AI features fail explicitly when not properly configured

Future Enhancements

Potential improvements to consider:

Enhanced AI Integration
- GitHub Copilot CLI integration
- OpenAI implementation completion
- Intelligent changelog enhancement
- Automated breaking change detection
Release Notes Intelligence
- Auto-generate release notes from PR content
- Highlight important changes for users
- Include migration guides for breaking changes
Cross-Repository Integration
- Notify dependent packages of new releases
- Coordinate releases across multiple packages
- Version compatibility checking
Advanced Analytics
- Release cadence optimization
- Change impact analysis
- User adoption tracking