78 lines
2.6 KiB
Markdown
78 lines
2.6 KiB
Markdown
# 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
|