# Versioning and Release Management
This project uses automatic version management powered by Git tags and `setuptools_scm`. The version is dynamically generated during installation and build processes.

## Key Features
- **Automatic Versioning**: Version derived from Git tags (e.g., `v1.2.3` → `1.2.3`)
- **Development Versions**: Unreleased commits show as `1.2.4.dev1+gabcdef12` (includes commit ID by default)
- **CI/CD Integration**: GitHub Actions validate version-tag alignment
- **Semantic Versioning**: Enforces proper version format in tags
- **Customizable Local Scheme**: Control how development versions are formatted (e.g., include/exclude commit ID)
- **Fallback Version**: `0.0.0` (if no tags exist)

## Creating Releases
```bash
# Create annotated tag
git tag -a v0.0.2 -m "Release version 0.0.2"
git push --tags

# Verify version
uv run python -c "import py_launch_blueprint; print(py_launch_blueprint.__version__)"
```

## Daily Development with Version Management
```bash
# Install with development dependencies
uv pip install --editable ".[dev]"

# Check current version
uv run python -c "import py_launch_blueprint; print(py_launch_blueprint.__version__)"

# Build package
hatch build
```

## Customizing Development Versions
The format of development versions can be customized using the `local_scheme` option in `pyproject.toml`. By default, the commit ID is included (e.g., `1.2.4.dev1+gabcdef12`). To change this behavior:

### Example: Remove Commit ID
```toml
[tool.hatch.version.raw-options]
local_scheme = "no-local-version"  # Excludes commit ID
```
Output:
```
1.2.4.dev1
```

### Example: Include Commit ID and Date
```toml
[tool.hatch.version.raw-options]
local_scheme = "node-and-date"  # Include commit ID and date
```
Output:
```
1.2.4.dev1+gabcdef12.d20231025
```

### Common `local_scheme` Options
| Scheme                | Example Output                     | Description                                  |
|-----------------------|------------------------------------|----------------------------------------------|
| `"no-local-version"`  | `1.2.4.dev1`                       | No commit ID or dirty flag                   |
| `"node-and-date"`     | `1.2.4.dev1+gabcdef12.d20231025`   | Commit ID and date                           |
| `"node-and-timestamp"`| `1.2.4.dev1+gabcdef12.1698249600`  | Commit ID and timestamp                      |
| `"dirty-tag"`         | `1.2.4.dev1+gabcdef12.dirty`       | Commit ID and dirty flag                     |
| `"local-version"`     | `1.2.4.dev1+gabcdef12`             | Commit ID only                               |

---

## CI/CD Automation
The pre-configured GitHub Actions workflow (`release.yml`) ensures a robust release process. Here's how it works:

### Workflow Steps
1. **Trigger**: Pushing a tag (e.g., `v1.0.0`) triggers the workflow.
2. **Checkout**: The repository is checked out with full Git history (`fetch-depth: 0`) to enable `setuptools_scm` version detection.
3. **Setup**:
   - Installs `uv` for fast dependency management.
   - Sets up Python using the specified version.
4. **Build**:
   - Installs build tools (`hatch` and `build`).
   - Builds the package using `hatch build`.
5. **Version Validation**:
   - Extracts the version from the Git tag (e.g., `v1.0.0` → `1.0.0`).
   - Compares it with the package version generated by `setuptools_scm`.
   - Fails if there’s a mismatch.
6. **Output**:
   - If successful, the built distributions are available in the `dist/` directory.

---

## Troubleshooting Versions

### Version Issues
- **Version shows 0.0.0**: Create initial Git tag (`v0.1.0`).
- **Version mismatch in CI**: Ensure GitHub Actions uses `fetch-depth: 0`.
- **Dirty version suffix**: Commit all changes before tagging.
- **Missing commit ID**: Check the `local_scheme` setting in `pyproject.toml`.

### Workflow Issues
- **Workflow not triggered**: Ensure the tag follows the `v*` format (e.g., `v1.0.0`).
- **Build failures**: Check the `pyproject.toml` configuration and dependencies.