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

gitflow_analytics-1.0.3/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+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
+- Path exclusion support for filtering boilerplate/generated files from line count metrics
+  - Configurable via `analysis.exclude.paths` in YAML configuration
+  - Default exclusions for common patterns (node_modules, lock files, minified files, etc.)
+  - Filtered metrics available as `filtered_insertions`, `filtered_deletions`, `filtered_files_changed`
+- JIRA integration for fetching story points from tickets
+  - Configurable story point field names via `jira_integration.story_point_fields`
+  - Automatic story point extraction from JIRA tickets referenced in commits
+  - Support for custom field IDs and field names
+- Organization-based repository discovery from GitHub
+  - Automatic discovery of all non-archived repositories in an organization
+  - No manual repository configuration needed for organization-wide analysis
+- Ticket platform filtering via `analysis.ticket_platforms`
+  - Ability to track only specific platforms (e.g., only JIRA, ignoring GitHub Issues)
+- Enhanced `.env` file support
+  - Automatic loading from configuration directory
+  - Validation of required environment variables
+  - Clear error messages for missing credentials
+- New CLI command: `discover-jira-fields` to find custom field IDs
+
+### Changed
+- All report generators now use filtered line counts when available
+- Cache and output directories now default to config file location (not current directory)
+- Improved developer identity resolution with better consolidation
+
+### Fixed
+- Timezone comparison errors between GitHub and local timestamps
+- License configuration in pyproject.toml for PyPI compatibility
+- Manual identity mapping format validation
+- Linting errors for better code quality
+
+### Documentation
+- Added comprehensive environment variable configuration guide
+- Complete configuration examples with `.env` and YAML files
+- Path exclusion documentation with default patterns
+- Updated README with clearer setup instructions
+
+## [1.0.0] - 2025-07-29
+
+### Added
+- Initial release of GitFlow Analytics
+- Core Git repository analysis with batch processing
+- Developer identity resolution with fuzzy matching
+- Manual identity mapping support
+- Story point extraction from commit messages
+- Multi-platform ticket tracking (GitHub, JIRA, Linear, ClickUp)
+- Comprehensive caching system with SQLite
+- CSV report generation:
+  - Weekly metrics
+  - Developer statistics
+  - Activity distribution
+  - Developer focus analysis
+  - Qualitative insights
+- Markdown narrative reports with insights
+- JSON export for API integration
+- DORA metrics calculation:
+  - Deployment frequency
+  - Lead time for changes
+  - Mean time to recovery
+  - Change failure rate
+- GitHub PR enrichment (optional)
+- Branch to project mapping
+- YAML configuration with environment variable support
+- Progress bars for long operations
+- Anonymization support for reports
+
+### Configuration Features
+- Repository definitions with project keys
+- Story point extraction patterns
+- Developer identity similarity threshold
+- Manual identity mappings
+- Default ticket platform specification
+- Branch mapping rules
+- Output format selection
+- Cache TTL configuration
+
+### Developer Experience
+- Clear CLI with helpful error messages
+- Comprehensive documentation
+- Sample configuration files
+- 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.0 → gitflow_analytics-1.0.3}/CLAUDE.md

@@ -42,9 +42,28 @@ The project uses SQLite for caching:
 
 Configuration uses YAML with environment variable support:
 - Variables use format: `${VARIABLE_NAME}`
+- **Environment files**: Automatically loads `.env` file from same directory as config YAML
+- **Organization support**: `github.organization` field enables automatic repository discovery
+- **Directory defaults**: Cache and reports now default to config file directory (not current working directory)
 - Default ticket platform can be specified
 - Branch mapping rules for project inference
 - Manual identity mappings for consolidating developer identities
+- Full backward compatibility with existing repository-based configurations
+
+#### Using .env Files
+
+The system automatically looks for a `.env` file in the same directory as your configuration YAML:
+```bash
+# Example .env file
+GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+JIRA_ACCESS_USER=your.email@company.com
+JIRA_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxx
+```
+
+This approach is recommended for:
+- Keeping credentials out of configuration files
+- Easy credential management across environments
+- Preventing accidental credential commits
 
 ### 5. Report Generation
 
@@ -87,6 +106,40 @@ When testing changes:
 3. Clear cache and re-run analysis
 4. Check for typos in email addresses
 
+#### Working with Organization Support
+
+1. **Organization Discovery**: When `github.organization` is specified and no repositories are manually configured:
+   - All non-archived repositories are automatically discovered from the GitHub organization
+   - Repositories are cloned to local directories if they don't exist
+   - Uses the organization name as the project key prefix if not specified
+
+2. **Testing Organization Configs**:
+   ```bash
+   # Test with organization discovery
+   gitflow-analytics analyze -c config-org.yaml --weeks 4 --validate-only
+   
+   # Run with discovered repositories
+   gitflow-analytics analyze -c config-org.yaml --weeks 4
+   ```
+
+3. **Directory Structure**: With organization support, the recommended directory structure is:
+   ```
+   /project/
+   ├── config-org.yaml       # Organization config
+   ├── repos/                # Auto-cloned repositories
+   │   ├── repo1/
+   │   ├── repo2/
+   │   └── repo3/
+   ├── .gitflow-cache/       # Cache (relative to config)
+   └── reports/              # Reports (default output location)
+   ```
+
+4. **Debugging Organization Discovery**:
+   - Check GitHub token has organization read permissions
+   - Verify organization name is correct (case-sensitive)
+   - Use `--validate-only` to test configuration without full analysis
+   - Check for API rate limiting issues
+
 ### 8. Performance Considerations
 
 - **Batch processing**: Commits are processed in batches (default: 1000)
@@ -145,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
 
@@ -169,6 +297,11 @@ gitflow-analytics/
 3. **Memory usage**: Large repositories can consume significant memory
 4. **Identity resolution**: Manual mappings must be applied after initial analysis
 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
 
@@ -191,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