# Version Management

This project uses automatic version synchronization between the `.env` file and `pyproject.toml`.

## Overview

The version is maintained in the `.env` file as the single source of truth, and automatically synchronized to `pyproject.toml` using the provided script.

## Files Involved

- **`.env`**: Contains `VERSION="x.y.z"` - the authoritative version source
- **`pyproject.toml`**: Contains `version = "x.y.z"` in the `[project]` section
- **`uv.lock`**: Lock file updated automatically to reflect version changes
- **`scripts/update_version.py`**: Python script that reads from `.env` and updates both files

## Usage

### Manual Update

```bash
# Update pyproject.toml version from .env (and sync uv.lock)
python scripts/update_version.py

# Or use the Makefile target
make update-version

# Skip uv.lock update if needed
python scripts/update_version.py --skip-uv-lock
make update-version-only
```

### Automatic Update

The script can be integrated into your development workflow in several ways:

1. **Before builds**: Run `make update-version` before building
2. **In CI/CD**: Add the script to your deployment pipeline
3. **As a pre-commit hook**: Add to `.pre-commit-config.yaml` (optional)

### Workflow

1. **Update the version**: Edit the `VERSION` variable in `.env`
2. **Synchronize**: Run `make update-version` or `python scripts/update_version.py`
3. **Verify**: All files now have the same version (`.env`, `pyproject.toml`, `uv.lock`)
4. **Commit**: All files can be committed together

## Examples

```bash
# Change version in .env
echo 'VERSION="1.14.0"' > .env  # (update just the VERSION line)

# Sync to pyproject.toml and uv.lock
make update-version

# Result: All files now have version 1.14.0
```

## Script Features

- **Comprehensive updates**: Updates both `pyproject.toml` and `uv.lock` automatically
- **Precise targeting**: Only updates the `version` field in the `[project]` section
- **Safe operation**: Leaves other version fields untouched (`minversion`, `target-version`, etc.)
- **Flexible options**: Can skip `uv.lock` update with `--skip-uv-lock` flag
- **Error handling**: Validates file existence, uv installation, and command success
- **Safety checks**: Shows current vs new version before changing
- **Idempotent**: Safe to run multiple times
- **Minimal dependencies**: Only uses Python standard library + uv
- **Clear output**: Shows exactly what changed

## Integration

The script is designed to be:
- **Fast**: Minimal overhead for CI/CD pipelines
- **Reliable**: Robust error handling and validation
- **Flexible**: Can be called from Make, CI, or manually
- **Maintainable**: Clear code with type hints and documentation