Gitflow-analytics

make release-major


That's it! The Makefile handles everything automatically.

Prerequisites

Required Tools

- **Python 3.9+**: The project runtime
- **Git**: For version control and tagging
- **pip**: For package management

Required Permissions

- **Git**: Push access to `main` branch and tags
- **PyPI**: API token with upload permissions

Environment Variables

Create a `.env.local` file in the project root:

bash
Required for PyPI publishing
PYPI_API_TOKEN=pypi-your-token-here

Optional: for TestPyPI
TEST_PYPI_API_TOKEN=pypi-your-test-token-here


**Get Your PyPI Token:**

1. Go to https://pypi.org/manage/account/token/
2. Create a new API token
3. Scope it to the `gitflow-analytics` project (recommended)
4. Copy the token (starts with `pypi-`)
5. Add to `.env.local` (never commit this file!)

Release Workflow

Understanding the Process

A complete release involves these steps:

1. **Quality Gate**: Run tests and linting
2. **Version Bump**: Update version number
3. **Build**: Create distribution packages
4. **Validation**: Verify everything is ready
5. **Git Tag**: Tag the release version
6. **Git Push**: Push code and tags to GitHub
7. **Publish**: Upload to PyPI

The Makefile automates all of these steps.

Full Release Process

bash
One-command release (recommended)
make release-patch or release-minor, or release-major

This will:
1. Run all tests
2. Run linting checks
3. Bump the version
4. Commit the version change
5. Build distribution packages
6. Validate packages
7. Check git status is clean
8. Create and push git tag
9. Publish to PyPI (if token configured)


Step-by-Step Release

If you prefer more control:

bash
1. Ensure quality
make quality-gate

2. Bump version
make version-patch or version-minor, or version-major

3. Build packages
make build

4. Check release readiness
make release-check

5. Complete the release
make release


Manual Version Management

bash
Check current version
make version

Bump versions manually
make version-patch 3.13.1 → 3.13.2
make version-minor 3.13.1 → 3.14.0
make version-major 3.13.1 → 4.0.0

Or set specific version
python scripts/manage_version.py set --version 4.0.0
git add src/gitflow_analytics/_version.py
git commit -m "chore: bump version to 4.0.0"


Common Tasks

Development Workflow

bash
Install for development
make install-dev

Run tests
make test

Format code
make format

Run linting
make lint

Run all quality checks
make quality-gate


Testing

bash
All tests
make test

Unit tests only
make test-unit

Integration tests only
make test-integration

With coverage report
make test-cov


Code Quality

bash
Check code style (no changes)
make lint

Auto-fix code style issues
make lint-fix

Format code (alias for lint-fix)
make format

Type checking (if configured)
make type-check

Security scanning
make security-check


Building

bash
Clean build artifacts
make clean

Build distribution packages
make build

Clean everything (including caches)
make clean-all


Version Information

bash
Show current version
make version

Show environment and configuration
make show-env

Show development status
make dev-status


PyPI Publishing

Publishing to PyPI

bash
Publish latest build to PyPI
make publish

Prerequisites:
- PYPI_API_TOKEN must be set in .env.local
- Packages must be built (make build)


Publishing to TestPyPI

bash
Publish to TestPyPI for testing
make publish-test

Prerequisites:
- TEST_PYPI_API_TOKEN set in .env.local
- Or PYPI_API_TOKEN will be used as fallback


Testing Published Packages

bash
Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ gitflow-analytics

Install from PyPI
pip install gitflow-analytics


Troubleshooting

Git Working Directory Not Clean

**Problem**: `make release` fails with "Git working directory is not clean"

**Solution**:
bash
Check what's uncommitted
git status

Commit or stash changes
git add .
git commit -m "your message"

Or stash for later
git stash


Version Already Released

**Problem**: "Version X.Y.Z already released"

**Solution**:
bash
Bump the version first
make version-patch or version-minor, or version-major

Then release
make release


PyPI Token Not Set

**Problem**: "PYPI_API_TOKEN not set"

**Solution**:
bash
Create .env.local file
echo 'PYPI_API_TOKEN=pypi-your-token-here' > .env.local

Verify it's loaded
make show-env


Test Failures

**Problem**: `make release` fails during tests

**Solution**:
bash
Run tests to see failures
make test

Fix the failing tests
Then run full quality gate
make quality-gate

Once passing, retry release
make release-patch


Build Failures

**Problem**: Build step fails

**Solution**:
bash
Clean build artifacts
make clean-all

Reinstall dependencies
make install-dev

Try building again
make build


Package Already Exists on PyPI

**Problem**: "File already exists" when publishing

**Solution**:
bash
You cannot overwrite published packages
Must bump version and release again

Bump version
make version-patch

Create new release
make release


Missing Dependencies

**Problem**: "Command not found: pytest/ruff/black"

**Solution**:
bash
Install all development dependencies
make install-dev

Or install specific tools
pip install pytest ruff black mypy bandit


Advanced Usage

Custom Release Workflow

bash
1. Make your changes
git add .
git commit -m "feat: add new feature"

2. Run quality checks
make quality-gate

3. Bump version for your change type
make version-minor for features
or
make version-patch for bug fixes

4. Build and validate
make build
make release-check

5. Complete release
make release


Pre-release Versions

bash
Set a pre-release version manually
python scripts/manage_version.py set --version 4.0.0-beta.1

Commit it
git add src/gitflow_analytics/_version.py

Build and publish to TestPyPI
make build
make publish-test


Hotfix Releases

bash
1. Create hotfix branch from latest release tag

Added
- **`--week YYYY-Www`** flag on `gfa collect`, `gfa classify`, and `gfa report` — target a specific ISO week (repeatable for multiple discrete weeks) (70)
- **`--from YYYY-Www --to YYYY-Www`** flag pair on all three commands — target an inclusive ISO week range (70)
- `src/gitflow_analytics/utils/iso_week.py` — `parse_iso_week()` and `iso_week_range()` helpers for ISO 8601 week string parsing
- `_resolve_date_range()` shared helper in CLI centralises mutual-exclusivity validation for all three commands

Changed
- `--week`/`--from`/`--to` are mutually exclusive with an explicit `--weeks N` value; clear UsageError is raised when combined
- Progress output shows ISO week range when targeted: `Classifying 2026-W01 → 2026-W07 (targeted window)`
- Taxonomy-only remaps (`work_type` label updates via `taxonomy_mapping` config) still apply instantly regardless of targeted window

Added
- **`platform` native change_type**: New first-class classifier category distinct from `maintenance` — captures deliberate infrastructure/architectural investment, internal tooling, and DevOps improvements. LLM prompt updated to distinguish `platform` (new capability) from `maintenance` (routine upkeep). Fallback patterns and NLP classifier updated. (69)
- **Config-driven taxonomy mapping**: `taxonomy_mapping.change_type` config block maps gfa's native `change_type` values to custom org-specific labels (e.g. `maintenance` → "KTLO", `platform` → "Platform work"). (69)
- **`work_type` column** on `qualitative_commits` (v18 migration): populated from `taxonomy_mapping` when configured; falls back to `change_type` when no mapping is present. (69)
- **Fast taxonomy remap**: `gfa classify --reclassify` applies taxonomy mapping to all historical commits in seconds — no LLM calls required for pure label remaps. (69)

Changed
- `pipeline_report` now exposes `work_type` (with `change_type` fallback) on all commit dicts for downstream report rendering
- `platform` added to fallback patterns, NLP classifier, and ISSUETYPE_CHANGE_TYPE_MAP (Infrastructure → platform)

Fixed
- "Platform work" metric collapse resolved: `platform` change_type + taxonomy mapping provides a clean, unambiguous path from classifier output to org-specific analytics labels
- Pyright: string annotations for optional spaCy `Doc` type in `change_type.py`

Fixed
- Mark unused method parameters as intentionally discarded to silence Pyright warnings
- Silence SQLAlchemy `Column` type errors in `batch_classifier_impl` via targeted ` type: ignore` comments
- Remove unused variable warnings in batch classifier and issuetype tests

Added
- **Tier-1.5 issuetype classifier**: Issue-linked commits are now classified via their JIRA/GH ticket `issuetype` field (confidence 0.90) before falling through to the LLM — eliminates LLM overhead for commits where the ticket type already encodes the answer (68)
- `IssueCache.issue_type` column (v17 migration) — `issuetype` extracted from JIRA API response during sync and stored as a queryable top-level field
- `business_domain` now populated from ticket `components` / `labels` for issue-linked commits (was always "unknown")
- Issuetype → change_type mapping: Bug→bugfix, Story/Feature/Epic→feature, Task+platform-label→maintenance, Task+refactor-label→refactor, Documentation→documentation, Test→test; ambiguous Task/Sub-task falls through to LLM

Fixed
- "Platform work" metric no longer collapses to 0% — issue-linked commits with Bug/Story/Task issuetype bypass the gitflow_cache rule-based path (which cannot produce "Platform work") and use the authoritative ticket signal instead