# Version Management

## Current Version: 0.4.2

## Single Source of Truth

The version is defined in **one place only** in the code:

```
src/tablesleuth/__init__.py
```

All other parts of the codebase import from this location.

## How to Update Version

### 1. Update the Version Number

Edit `src/tablesleuth/__init__.py`:

```python
__version__ = "0.5.0"  # Update this line
```

### 2. Update CHANGELOG.md

Add a new section at the top:

```markdown
## [0.5.0] - YYYY-MM-DD

### Added
- New feature descriptions

### Changed
- Changed feature descriptions

### Fixed
- Bug fix descriptions
```

### 3. Verify the Version

```bash
# Check that version is correct
python -c "from tablesleuth import __version__; print(__version__)"

# Build and verify
uv build
python -m zipfile -l dist/tablesleuth-*.whl | grep METADATA
```

### 4. Commit and Tag

```bash
# Commit changes
git add src/tablesleuth/__init__.py CHANGELOG.md
git commit -m "Bump version to 0.5.0"

# Create and push tag
git tag -a v0.5.0 -m "Release v0.5.0"
git push origin main
git push origin v0.5.0
```

### 5. Create GitHub Release

1. Go to https://github.com/jamesbconner/TableSleuth/releases/new
2. Select the tag `v0.5.0`
3. Copy release notes from CHANGELOG.md
4. Publish release

GitHub Actions will automatically publish to PyPI.

## Version Locations

### Source of Truth
- `src/tablesleuth/__init__.py` - **ONLY place to edit version in code**

### Auto-Generated (Do Not Edit)
- `pyproject.toml` - Synced manually when needed
- `uv.lock` - Auto-generated by uv
- `dist/` - Build artifacts

### Imported From Source
- `src/tablesleuth/cli.py` - Imports `__version__` from package

### Documentation (Update Manually)
- `CHANGELOG.md` - Add new version section
- `README.md` - Update "What's New" section if needed
- `docs/DEVELOPER_GUIDE.md` - Update if major version
- `docs/ARCHITECTURE.md` - Update if major version
- `docs/PERFORMANCE_PROFILING.md` - Update if major version

## Semantic Versioning

We follow [Semantic Versioning 2.0.0](https://semver.org/):

- **MAJOR** (X.0.0) - Incompatible API changes
- **MINOR** (0.X.0) - New functionality, backwards compatible
- **PATCH** (0.0.X) - Bug fixes, backwards compatible

### Pre-release Versions

For pre-releases, use:
- `0.5.0a1` - Alpha release
- `0.5.0b1` - Beta release
- `0.5.0rc1` - Release candidate

### Post-release Versions

For hotfixes after release:
- `0.5.0.post1` - Post-release fix

## Automated Version Management (Future)

Consider using `hatch-vcs` for automatic version management from git tags:

```toml
[build-system]
requires = ["hatchling", "hatch-vcs"]

[tool.hatch.version]
source = "vcs"

[tool.hatch.build.hooks.vcs]
version-file = "src/tablesleuth/_version.py"
```

This would eliminate manual version updates entirely.

## Troubleshooting

### Version Mismatch

If you see version mismatches:

```bash
# Check all version references
grep -r "0\.4\.0" .

# Rebuild from clean state
make clean
uv build
```

### PyPI Won't Accept Version

PyPI doesn't allow re-uploading the same version:

1. Increment the version number
2. Rebuild: `uv build`
3. Upload again: `twine upload dist/*`

### Git Tag Already Exists

If you need to move a tag:

```bash
# Delete local tag
git tag -d v0.5.0

# Delete remote tag
git push origin :refs/tags/v0.5.0

# Create new tag
git tag -a v0.5.0 -m "Release v0.5.0"
git push origin v0.5.0
```

## Checklist for Release

- [ ] Update `src/tablesleuth/__init__.py` version
- [ ] Update `pyproject.toml` version
- [ ] Update `CHANGELOG.md`
- [ ] Update `README.md` "What's New" section
- [ ] Run tests: `make test`
- [ ] Run quality checks: `make check`
- [ ] Run pre-commit checks: `make pre-commit`
- [ ] Build package: `uv build`
- [ ] Test locally: `pip install dist/tablesleuth-*.whl`
- [ ] Commit changes
- [ ] Create and push git tag
- [ ] Create GitHub release
- [ ] Verify PyPI publication (automatic via GitHub Actions)
