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¶

# 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¶

# 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¶

[tool.hatch.version.raw-options]
local_scheme = "no-local-version"  # Excludes commit ID

Output:

1.2.4.dev1

Example: Include Commit ID and Date¶

[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.