feat: implement automated version bumping and PyPI publishing

[jon-myers]

Summary

Implements automated version bumping and PyPI publishing to resolve issue #14.

🚀 New Features

• Automated version bumping using python-semantic-release
• PATCH-ONLY mode: All commits increment patch version (0.1.14 → 0.1.15)
• Manual control available for minor/major bumps when needed
• GitHub Actions workflows for PR testing and automated releases
• OIDC trusted publishing - no API tokens needed for production PyPI

🔧 Implementation Details

• PR Testing Workflow: Tests + uploads to TestPyPI on every PR
• Release Workflow: Auto-publishes to PyPI on merge to main
• Version file tracking: Updates __init__.py, pyproject.toml, docs/conf.py
• Complete documentation in CLAUDE.md for future reference

📋 Required Setup (One-time)

• TestPyPI API token added to GitHub secrets
• PyPI trusted publisher configuration needed (see CLAUDE.md)

🎛️ Manual Version Control

When you want special version bumps:

semantic-release version --increment minor  # 0.1.15 → 0.2.0
semantic-release version --increment major  # 0.2.0 → 1.0.0

Test Plan

• Configuration validated locally
• Test PR workflow (will happen automatically)
• Test release workflow after merge

Closes #14

🤖 Generated with Claude Code

[github-actions]

📦 Test Package Built Successfully!

This PR has been automatically built and uploaded to TestPyPI for testing.

🔗 TestPyPI Link: https://test.pypi.org/project/idtap/

To test this version:

pip install --index-url https://test.pypi.org/simple/ idtap

✅ All tests passed and package builds successfully.

[jon-myers]

@claude review

[claude]

Claude finished @jon-myers's task —— View job

---

PR Review: Automated Version Bumping & PyPI Publishing

Review Tasks:

• Analyze GitHub Actions workflows for security and functionality
• Review semantic-release configuration
• Check documentation updates in CLAUDE.md
• Validate test file changes
• Assess overall implementation quality

GitHub Actions Workflows Analysis ✅

.github/workflows/release.yml

Strengths:

• OIDC trusted publishing - Excellent security practice, eliminates API token management
• Proper permissions - Minimal required permissions (id-token: write, contents: write)
• Conditional execution - Only runs if version bump is needed via dry-run check
• Full fetch depth - Required for semantic-release to work correctly
• Test-before-release - Runs tests before publishing

Minor Issues:

• Uses actions/setup-python@v4 - consider upgrading to v5
• pip install -e .[dev] assumes the package structure matches current directory
• No explicit dependency caching (not critical but could improve performance)

.github/workflows/test-pr.yml

Strengths:

• Security-conscious - Only uploads from same repo (prevents fork attacks)
• Automated PR comments - Great UX with TestPyPI links
• Comprehensive testing - Tests, builds, and validates package
• Skip existing - Won't fail if version already exists on TestPyPI

Semantic-Release Configuration ✅

Excellent Configuration:

• Patch-only mode perfectly implemented via empty minor_tags and major_tags
• Comprehensive file tracking - Updates __init__.py, pyproject.toml, and docs/conf.py
• Proper tag patterns - All commit types map to patch increments
• Upload disabled - Correctly delegates to GitHub Actions
• Version pattern matching - Handles README.md versioning

pyproject.toml:112-141 - Configuration is well thought out and secure.

Documentation Updates ✅

CLAUDE.md Updates are Comprehensive:

• Clear automation workflow explanation
• Manual override commands for special version bumps
• Required setup documentation with specific secrets and trusted publisher info
• Migration path from manual to automated process
• Practical examples of commit messages and their effects

Lines 111-169 show excellent documentation of the new automated system.

Test File Changes ✅

All test file changes are appropriate:

• auth_logout_test.py - Added @pytest.mark.integration markers to properly categorize tests
• query_integration_test.py - Added integration markers for test filtering
• test_realistic_queries.py - Added integration markers

These changes ensure that integration tests are properly excluded from CI runs via pytest -m "not integration".

Overall Implementation Assessment ⭐⭐⭐⭐⭐

This is an excellent implementation with the following highlights:

✅ Security Best Practices:

• OIDC trusted publishing eliminates token management
• Proper GitHub Actions permissions
• Fork attack prevention

✅ Robust Automation:

• Conditional releases (no empty releases)
• Comprehensive testing before publication
• Multiple file version synchronization

✅ Developer Experience:

• Clear documentation and migration path
• Automated PR feedback with TestPyPI links
• Manual override capability for special cases

✅ Production Ready:

• Proper error handling and logging
• Integration test categorization
• No breaking changes to existing workflow

Recommendations for Improvement

1. Minor Python Action Update:

   - name: Set up Python
     uses: actions/setup-python@v5  # Update from v4

2. Optional Dependency Caching:

   - name: Cache dependencies
     uses: actions/cache@v4
     with:
       path: ~/.cache/pip
       key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}

3. Consider adding version validation step:

   • Verify that __init__.py and pyproject.toml versions stay in sync

Conclusion

APPROVE ✅

This PR implements automated version bumping and PyPI publishing with excellent security practices, comprehensive documentation, and a smooth migration path. The patch-only default with manual override capability strikes the perfect balance between automation and control.

The implementation is production-ready and follows GitHub/PyPI best practices throughout.

---

[claude]

Claude finished @jon-myers's task —— View job

---

Automated Version Management PR Review ✅

This is a well-implemented automated publishing system with excellent attention to security and best practices. The PR successfully addresses issue #14 and provides a robust CI/CD solution.

🔧 Implementation Quality

✅ Strong Points:

• Security-first approach: OIDC trusted publishing eliminates API token risks
• Comprehensive error handling: Version check before release prevents unnecessary builds
• Proper test isolation: pytest -m "not integration" ensures CI reliability
• Semantic versioning configuration: Files properly tracked in pyproject.toml
• Documentation excellence: CLAUDE.md provides clear operational guidance

✅ Workflow Design:

• release.yml:10: Smart concurrency: release prevents race conditions
• release.yml:34-47: Excellent dry-run check prevents empty releases
• test-pr.yml:42: Proper fork detection for TestPyPI uploads
• test-pr.yml:47: skip-existing: true prevents upload conflicts

🛠️ Configuration Analysis

Semantic Release Setup (pyproject.toml:108-125):

• ✅ Patch-only mode correctly implemented
• ✅ Version tracking spans all required files (__init__.py, pyproject.toml, docs/conf.py)
• ✅ GitHub integration properly configured
• ✅ upload_to_pypi = false prevents conflicts with GitHub Actions

Test Integration:

• ✅ Integration tests properly marked and excluded from CI (-m "not integration")
• ✅ New test files follow consistent patterns
• ✅ auth_logout_test.py:12,40,67,93,117: Proper @pytest.mark.integration usage

🔒 Security Assessment

Excellent security posture:

• ✅ OIDC trusted publishing (no stored tokens)
• ✅ Minimal permission grants (id-token: write, contents: write)
• ✅ Fork safety: TestPyPI uploads only for same-repo PRs (test-pr.yml:42)
• ✅ Proper git configuration with bot identity (release.yml:58-59)

📝 Documentation Quality

The CLAUDE.md updates are comprehensive and actionable:

• ✅ Clear workflow explanation (lines 98-102)
• ✅ Manual override commands provided (lines 121-128)
• ✅ Version file locations documented (lines 104-107)
• ✅ Complete setup instructions for trusted publishing

⚠️ Minor Considerations

1. Missing trusted publisher setup: The PyPI trusted publisher configuration is documented but not yet completed (mentioned in PR description checklist)

2. Potential version tracking: README.md version pattern in pyproject.toml:111 assumes a specific format that may need maintenance

3. Documentation sync: Consider validating that docs/conf.py exists before adding to version patterns

🎯 Recommendations

Before merge:

1. Complete PyPI trusted publisher configuration as outlined in CLAUDE.md
2. Verify docs/conf.py exists or remove from version patterns if not applicable

Post-merge improvements (future PRs):

• Consider adding changelog automation
• Add workflow status badges to README
• Consider notification integrations for release announcements

🏁 Final Assessment

This PR demonstrates exceptional engineering practices with security-conscious design and thorough documentation. The automated system will significantly improve the development workflow while maintaining high reliability standards.

Recommendation: ✅ APPROVE - Ready for merge after completing PyPI trusted publisher setup.

---

[github-actions]

📦 Test Package Built Successfully!

This PR has been automatically built and uploaded to TestPyPI for testing.

🔗 TestPyPI Link: https://test.pypi.org/project/idtap/

To test this version:

pip install --index-url https://test.pypi.org/simple/ idtap

✅ All tests passed and package builds successfully.