gitflow-analytics 1.0.1__tar.gz → 1.0.3__tar.gz

{gitflow_analytics-1.0.1 → gitflow_analytics-1.0.3}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to GitFlow Analytics 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).
 
+## [1.0.3] - 2025-08-01
+
+### Fixed
+- Fixed comprehensive timezone comparison issues in database queries and report generation
+- Improved timezone-aware datetime handling across all components
+- Fixed timezone-related errors that were still affecting v1.0.2
+
+## [1.0.2] - 2025-08-01
+
+### Fixed
+- Fixed SQLite index naming conflicts that could cause database errors
+- Fixed PR cache UNIQUE constraint errors with proper upsert logic
+- Fixed timezone comparison errors in report generation
+- Added loading screen to TUI (before abandoning TUI approach)
+- Moved Rich to core dependencies for better CLI output
+
 ## [1.0.1] - 2025-07-31
 
 ### Added
@@ -90,5 +106,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Progress indicators during analysis
 - Detailed logging of operations
 
+[1.0.3]: https://github.com/bobmatnyc/gitflow-analytics/releases/tag/v1.0.3
+[1.0.2]: https://github.com/bobmatnyc/gitflow-analytics/releases/tag/v1.0.2
 [1.0.1]: https://github.com/bobmatnyc/gitflow-analytics/releases/tag/v1.0.1
 [1.0.0]: https://github.com/bobmatnyc/gitflow-analytics/releases/tag/v1.0.0

{gitflow_analytics-1.0.1 → gitflow_analytics-1.0.3}/CLAUDE.md

@@ -198,22 +198,97 @@ gitflow-analytics/
 └── README.md                # User documentation
 ```
 
-## Version Management
+## Atomic Versioning System
 
-- Version is stored in `src/gitflow_analytics/_version.py`
-- Follow semantic versioning (MAJOR.MINOR.PATCH)
-- Update version before releases
-- Tag releases with `v` prefix (e.g., `v1.0.0`)
+The project uses **python-semantic-release** for automated, atomic version management. This ensures consistency between the source code version, git tags, PyPI releases, and GitHub releases.
 
-## Release Process
+### Version Source of Truth
 
-1. Update version in `_version.py`
-2. Run full test suite
-3. Update CHANGELOG.md
-4. Commit with message: `chore: bump version to X.Y.Z`
-5. Tag the release: `git tag -a vX.Y.Z -m "Release version X.Y.Z"`
-6. Push tags: `git push origin main --tags`
-7. Build and publish to PyPI (see DEPLOY.md)
+The single source of truth for versioning is:
+- **File**: `src/gitflow_analytics/_version.py`
+- **Format**: `__version__ = "X.Y.Z"`
+- **Management**: Automatically updated by semantic-release
+
+### Semantic Versioning Rules
+
+Version bumps are determined by conventional commit messages:
+- **MAJOR** (X.0.0): Breaking changes (rare, manual intervention required)
+- **MINOR** (0.X.0): New features (`feat:` commits)
+- **PATCH** (0.0.X): Bug fixes and maintenance (`fix:`, `docs:`, `chore:`, etc.)
+
+### Conventional Commit Format
+
+Use these prefixes for automatic version detection:
+```bash
+# Minor version bump (new features)
+feat: add new story point extraction pattern
+feat(cli): add --validate-only flag for configuration testing
+
+# Patch version bump (fixes, improvements, maintenance)
+fix: resolve identity resolution bug with similar names
+fix(cache): handle database lock errors gracefully
+docs: update installation instructions
+chore: update dependency versions
+style: fix code formatting issues
+refactor: improve error handling in GitHub client
+perf: optimize commit batch processing
+test: add integration tests for organization discovery
+ci: update GitHub Actions workflow
+build: update pyproject.toml configuration
+```
+
+### CLI Version Display Fix
+
+The project includes a fix for proper CLI version display:
+- Version is dynamically imported from `_version.py`
+- CLI command `gitflow-analytics --version` correctly shows current version
+- Prevents version mismatch between package and CLI
+
+## Automated Release Process
+
+The project uses GitHub Actions for fully automated releases:
+
+### Workflow Triggers
+1. **Push to main branch**: Triggers semantic analysis
+2. **Manual dispatch**: Can be triggered manually via GitHub UI
+3. **Conventional commits**: Drive version bump decisions
+
+### Release Steps (Automated)
+1. **Semantic Analysis**: Analyze commits since last release
+2. **Version Calculation**: Determine next version based on commit types
+3. **Version Update**: Update `_version.py` with new version
+4. **Git Operations**: Create git tag and GitHub release
+5. **Quality Checks**: Run full test suite, linting, and type checking
+6. **Package Build**: Build wheel and source distributions
+7. **PyPI Publishing**: Automatically publish to PyPI
+8. **Asset Upload**: Attach build artifacts to GitHub release
+9. **Changelog**: Auto-generate and update CHANGELOG.md
+
+### Manual Override (Emergency Only)
+
+For emergency releases or version fixes:
+```bash
+# Only if semantic-release is not working
+git checkout main
+git pull origin main
+# Edit src/gitflow_analytics/_version.py manually
+git commit -m "chore(release): manual version bump to X.Y.Z"
+git tag -a vX.Y.Z -m "Emergency release X.Y.Z"
+git push origin main --tags
+```
+
+### GitHub Actions Configuration
+
+The project includes comprehensive CI/CD:
+- **`.github/workflows/semantic-release.yml`**: Main release workflow
+- **`.github/workflows/tests.yml`**: Testing on multiple Python versions
+- **`.github/workflows/release.yml`**: Additional release validation
+
+### PyPI Publishing
+
+- **Trusted Publishing**: Uses GitHub's OIDC for secure PyPI publishing
+- **No API Keys**: No need to manage PyPI tokens in secrets
+- **Automatic**: Publishing happens on every version tag creation
 
 ## Common Gotchas
 
@@ -224,6 +299,9 @@ gitflow-analytics/
 5. **Cache invalidation**: Some changes require clearing the cache
 6. **Directory defaults**: Cache and reports now default to config file directory, not current working directory
 7. **Organization permissions**: GitHub token must have organization read access for automatic repository discovery
+8. **Version conflicts**: Never manually edit version in `_version.py` unless bypassing semantic-release
+9. **Commit message format**: Incorrect commit message format will not trigger version bumps
+10. **Release permissions**: Only repository owners can trigger releases (configured in workflow)
 
 ## Quick Commands
 
@@ -246,6 +324,11 @@ black src/ tests/
 # Check code quality
 ruff check src/
 mypy src/
+
+# Version and release commands (automated via CI/CD)
+semantic-release version --dry-run  # Preview next version
+semantic-release version           # Create release (CI only)
+gitflow-analytics --version       # Check current version
 ```
 
 ## Contact

{gitflow_analytics-1.0.1 → gitflow_analytics-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 1.0.1
+Version: 1.0.3
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT
@@ -12,14 +12,13 @@ Keywords: git,analytics,productivity,metrics,development
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Version Control :: Git
 Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.1
@@ -30,6 +29,12 @@ Requires-Dist: pandas>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: python-dateutil>=2.8
 Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: spacy>=3.7.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: openai>=1.30.0
+Requires-Dist: tiktoken>=0.7.0
+Requires-Dist: numpy>=1.24.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
@@ -37,14 +42,26 @@ Requires-Dist: pytest-mock>=3.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
 Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: isort>=5.0; extra == "dev"
+Requires-Dist: bandit[toml]>=1.7; extra == "dev"
+Requires-Dist: safety>=2.0; extra == "dev"
+Requires-Dist: python-semantic-release>=8.0.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: types-requests>=2.28; extra == "dev"
 Provides-Extra: github
 Requires-Dist: pygithub>=1.58; extra == "github"
+Provides-Extra: tui
+Requires-Dist: textual>=0.41.0; extra == "tui"
 Provides-Extra: all
-Requires-Dist: gitflow-analytics[github]; extra == "all"
+Requires-Dist: gitflow-analytics[github,tui]; extra == "all"
 Dynamic: license-file
 
 # GitFlow Analytics
 
+[![PyPI version](https://badge.fury.io/py/gitflow-analytics.svg)](https://badge.fury.io/py/gitflow-analytics)
+[![Python Support](https://img.shields.io/pypi/pyversions/gitflow-analytics.svg)](https://pypi.org/project/gitflow-analytics/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 A Python package for analyzing Git repositories to generate comprehensive developer productivity reports. It extracts data directly from Git history and GitHub APIs, providing weekly summaries, productivity insights, and gap analysis.
 
 ## Features
@@ -64,10 +81,20 @@ A Python package for analyzing Git repositories to generate comprehensive develo
 
 ### Installation
 
+**From PyPI (Recommended):**
+
 ```bash
 pip install gitflow-analytics
 ```
 
+**From Source (Development):**
+
+```bash
+git clone https://github.com/bobmatnyc/gitflow-analytics.git
+cd gitflow-analytics
+pip install -e ".[dev]"
+```
+
 ### Basic Usage
 
 1. Create a configuration file (`config.yaml`):

{gitflow_analytics-1.0.1 → gitflow_analytics-1.0.3}/README.md

@@ -1,5 +1,9 @@
 # GitFlow Analytics
 
+[![PyPI version](https://badge.fury.io/py/gitflow-analytics.svg)](https://badge.fury.io/py/gitflow-analytics)
+[![Python Support](https://img.shields.io/pypi/pyversions/gitflow-analytics.svg)](https://pypi.org/project/gitflow-analytics/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 A Python package for analyzing Git repositories to generate comprehensive developer productivity reports. It extracts data directly from Git history and GitHub APIs, providing weekly summaries, productivity insights, and gap analysis.
 
 ## Features
@@ -19,10 +23,20 @@ A Python package for analyzing Git repositories to generate comprehensive develo
 
 ### Installation
 
+**From PyPI (Recommended):**
+
 ```bash
 pip install gitflow-analytics
 ```
 
+**From Source (Development):**
+
+```bash
+git clone https://github.com/bobmatnyc/gitflow-analytics.git
+cd gitflow-analytics
+pip install -e ".[dev]"
+```
+
 ### Basic Usage
 
 1. Create a configuration file (`config.yaml`):

gitflow_analytics-1.0.3/docs/DEPLOY.md

@@ -0,0 +1,308 @@
+# Deployment Guide for GitFlow Analytics
+
+This guide covers the deployment process for GitFlow Analytics. **As of v1.0.1, the project uses fully automated releases** via GitHub Actions and semantic-release. Manual deployment is only needed for emergency situations.
+
+## Table of Contents
+
+1. [Current Status](#current-status)
+2. [Automated Release Process](#automated-release-process)
+3. [Conventional Commits](#conventional-commits)
+4. [Monitoring Releases](#monitoring-releases)
+5. [Manual Deployment (Emergency Only)](#manual-deployment-emergency-only)
+6. [Legacy Manual Process](#legacy-manual-process)
+
+## Current Status
+
+**GitFlow Analytics v1.0.1 is live on PyPI!**
+
+- 📦 **PyPI Package**: [gitflow-analytics](https://pypi.org/project/gitflow-analytics/)
+- 🏷️ **Latest Version**: v1.0.1
+- 🚀 **Installation**: `pip install gitflow-analytics`
+- 🤖 **Release Method**: Fully automated via GitHub Actions
+
+## Automated Release Process
+
+The project uses **python-semantic-release** with GitHub Actions for fully automated deployments. This ensures:
+
+- ✅ Consistent versioning across all platforms
+- ✅ Automatic changelog generation
+- ✅ Secure PyPI publishing via trusted publishing
+- ✅ Atomic releases (git tag + GitHub release + PyPI upload)
+- ✅ Comprehensive testing before release
+
+### How It Works
+
+1. **Developer commits** using conventional commit format
+2. **GitHub Actions detects** push to main branch
+3. **Semantic-release analyzes** commits to determine version bump
+4. **Automated pipeline** runs:
+   - Updates `src/gitflow_analytics/_version.py`
+   - Creates git tag
+   - Runs full test suite
+   - Builds package
+   - Publishes to PyPI
+   - Creates GitHub release
+   - Updates CHANGELOG.md
+
+### Triggering a Release
+
+Simply push commits with conventional commit messages to the `main` branch:
+
+```bash
+git commit -m "feat: add new analysis feature"
+git push origin main  # This triggers the release pipeline
+```
+
+## Conventional Commits
+
+Use conventional commit messages to trigger automatic version bumps:
+
+### Commit Types and Version Impact
+
+| Commit Type | Version Bump | Example |
+|-------------|--------------|----------|
+| `feat:` | Minor (0.X.0) | `feat: add JIRA integration` |
+| `fix:` | Patch (0.0.X) | `fix: resolve identity resolution bug` |
+| `docs:` | Patch (0.0.X) | `docs: update installation guide` |
+| `chore:` | Patch (0.0.X) | `chore: update dependencies` |
+| `style:` | Patch (0.0.X) | `style: fix code formatting` |
+| `refactor:` | Patch (0.0.X) | `refactor: improve error handling` |
+| `perf:` | Patch (0.0.X) | `perf: optimize commit processing` |
+| `test:` | Patch (0.0.X) | `test: add integration tests` |
+| `ci:` | Patch (0.0.X) | `ci: update GitHub Actions` |
+| `build:` | Patch (0.0.X) | `build: update pyproject.toml` |
+
+### Breaking Changes
+
+For breaking changes (major version bump), add `BREAKING CHANGE:` in the commit body:
+
+```bash
+git commit -m "feat: redesign configuration format
+
+BREAKING CHANGE: Configuration file format has changed from YAML to TOML.
+Existing config.yaml files need to be converted to config.toml format."
+```
+
+### Commit Message Format
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Examples:
+```bash
+feat(cli): add --validate-only flag for configuration testing
+fix(cache): handle database lock errors gracefully  
+docs: add PyPI installation instructions
+chore(deps): update GitHub Actions to v4
+```
+
+## Monitoring Releases
+
+### Check Release Status
+
+1. **GitHub Actions**: Monitor the [semantic-release workflow](https://github.com/bobmatnyc/gitflow-analytics/actions/workflows/semantic-release.yml)
+2. **PyPI**: Check the [package page](https://pypi.org/project/gitflow-analytics/) for new versions
+3. **GitHub Releases**: View [releases page](https://github.com/bobmatnyc/gitflow-analytics/releases) for release notes
+
+### Release Workflow Logs
+
+The automated release process provides detailed logs:
+- Semantic analysis results
+- Version calculation logic
+- Test execution results
+- Build and publish status
+- Error details if any step fails
+
+### Troubleshooting Failed Releases
+
+If the automated release fails:
+
+1. **Check workflow logs** in GitHub Actions
+2. **Common issues**:
+   - Test failures block the release
+   - PyPI trusted publishing configuration
+   - GitHub token permissions
+   - Semantic-release configuration errors
+
+3. **Resolution**:
+   - Fix the underlying issue
+   - Push another commit to main
+   - The workflow will retry automatically
+
+## Manual Deployment (Emergency Only)
+
+**⚠️ Warning**: Manual deployment should only be used in emergency situations when the automated system is not working.
+
+### Prerequisites
+
+```bash
+pip install --upgrade pip build twine python-semantic-release
+```
+
+### Emergency Release Process
+
+1. **Manual version bump:**
+   ```bash
+   # Edit src/gitflow_analytics/_version.py manually
+   git commit -m "chore(release): emergency version bump to X.Y.Z"
+   ```
+
+2. **Create tag and build:**
+   ```bash
+   git tag -a vX.Y.Z -m "Emergency release X.Y.Z"
+   python -m build
+   ```
+
+3. **Test and publish:**
+   ```bash
+   python -m twine check dist/*
+   python -m twine upload dist/*
+   ```
+
+4. **Push to GitHub:**
+   ```bash
+   git push origin main --tags
+   ```
+
+### When to Use Manual Deployment
+
+- GitHub Actions is down for extended periods
+- Critical security fix needed immediately
+- Automated system configuration is broken
+- PyPI trusted publishing is not working
+
+### Recovery After Manual Release
+
+After manual deployment, ensure the automated system is working:
+
+1. Verify the version in `_version.py` matches the released version
+2. Ensure the git tag exists and is pushed
+3. Test the next automated release with a patch commit
+4. Update CHANGELOG.md if it wasn't auto-generated
+
+## Legacy Manual Process
+
+<details>
+<summary>Click to expand legacy manual deployment process (archived)</summary>
+
+**Note**: This section is kept for historical reference. The project now uses automated releases.
+
+### Manual Build Process (Deprecated)
+
+1. **Clean previous builds:**
+   ```bash
+   rm -rf dist/ build/ *.egg-info
+   ```
+
+2. **Build the package:**
+   ```bash
+   python -m build
+   ```
+
+3. **Verify the build:**
+   ```bash
+   ls -la dist/
+   ```
+
+### Manual PyPI Publishing (Deprecated)
+
+1. **Setup PyPI credentials** in `~/.pypirc`
+2. **Test with TestPyPI:**
+   ```bash
+   twine upload --repository testpypi dist/*
+   ```
+3. **Publish to PyPI:**
+   ```bash
+   twine upload dist/*
+   ```
+
+### Manual GitHub Release (Deprecated)
+
+1. **Tag the version:**
+   ```bash
+   git tag -a v1.0.0 -m "Release version 1.0.0"
+   ```
+2. **Create GitHub Release** via web interface
+3. **Attach build artifacts**
+
+</details>
+
+## Development Workflow
+
+### Feature Development and Release
+
+1. **Feature development:**
+   ```bash
+   git checkout -b feature/new-analysis-metric
+   # Make changes
+   git commit -m "feat: add DORA metrics calculation"
+   git push origin feature/new-analysis-metric
+   # Create PR
+   ```
+
+2. **Merge to main:**
+   ```bash
+   # After PR approval and merge
+   git checkout main
+   git pull origin main
+   # The semantic-release workflow automatically runs
+   ```
+
+3. **Release happens automatically:**
+   - Version is calculated from commit messages
+   - Package is built and tested
+   - PyPI release is published
+   - GitHub release is created
+   - CHANGELOG.md is updated
+
+### Hotfix Workflow
+
+```bash
+git checkout main
+git pull origin main
+git checkout -b hotfix/critical-bug
+# Fix the issue
+git commit -m "fix: resolve critical identity resolution bug"
+git push origin hotfix/critical-bug
+# Create PR, merge to main
+# Patch release happens automatically
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Build fails:**
+   - Ensure all dependencies are installed
+   - Check for syntax errors in setup files
+   - Verify `MANIFEST.in` includes all necessary files
+
+2. **Upload fails:**
+   - Check PyPI credentials
+   - Ensure version doesn't already exist
+   - Verify package name availability
+
+3. **Import errors after installation:**
+   - Check package structure
+   - Verify all modules are included
+   - Test locally with `pip install -e .`
+
+### Getting Help
+
+- [Python Packaging Guide](https://packaging.python.org)
+- [PyPI Help](https://pypi.org/help/)
+- [Project Issues](https://github.com/bobmatnyc/gitflow-analytics/issues)
+
+## See Also
+
+- [CLAUDE.md](../CLAUDE.md) - Developer instructions with detailed versioning info
+- [README.md](../README.md) - User documentation and installation
+- [CHANGELOG.md](../CHANGELOG.md) - Automatically generated version history
+- [PyPI Package](https://pypi.org/project/gitflow-analytics/) - Official package page
+- [GitHub Releases](https://github.com/bobmatnyc/gitflow-analytics/releases) - Release notes and downloads
+- [GitHub Actions](https://github.com/bobmatnyc/gitflow-analytics/actions) - CI/CD pipeline status