Version Management

AReaL implements a comprehensive version management system that tracks package versions, Git metadata, and release tagging. The system provides runtime version information enriched with Git commit hashes and repository state, enabling reproducibility and debugging of specific code states.

For build system and dependency management, see 12.2. Dependencies and Package Management For Docker image builds, see 12.3. Docker Images For CI/CD release processes, see 12.4. CI/CD Workflows

Overview

AReaL's version management follows a single source of truth principle where the canonical version is defined in pyproject.toml. At runtime, the system queries installed package metadata and enriches it with Git repository information (branch, commit hash, dirty status) to provide detailed version strings useful for debugging and reproducibility tracking.

Version Data Flow

The following diagram illustrates how version information flows from the static configuration into the runtime environment.

Title: Version Information Extraction and Propagation

Sources: areal/version.py9-97 .github/workflows/tag-release-image.yml136-137

Version Source of Truth

The package version is defined in pyproject.toml. This version string is the single source of truth for all version-related operations, including Docker builds and runtime reporting. During installation, this version is recorded in package metadata accessible via importlib.metadata.version() areal/version.py9-15

The CI/CD pipeline explicitly extracts this version during the release process to tag Docker images in the get-version step of the release workflow .github/workflows/tag-release-image.yml133-144

Sources: areal/version.py9-15 .github/workflows/tag-release-image.yml133-144

VersionInfo Class

The VersionInfo class in areal/version.py provides structured access to version information and Git metadata areal/version.py18-89

Class Structure

Property	Type	Source	Description
version	str	Package metadata	Canonical package version (e.g., "1.0.4") areal/version.py26-28
branch	str	Git	Current branch name areal/version.py30-32
commit	str	Git	Short commit hash (e.g., "abc1234") areal/version.py34-36
is_dirty	bool	Git	Whether working directory has uncommitted changes areal/version.py38-40
full_version	str	Computed	Combined version with Git metadata areal/version.py42-49
full_version_with_dirty_description	str	Computed	Full version with human-readable dirty explanation areal/version.py51-58

Implementation Logic

The following diagram maps the VersionInfo implementation to system commands and metadata sources.

Title: VersionInfo Runtime Population

Sources: areal/version.py18-89

Git Metadata Collection

The _populate_version_info() method uses subprocess to query Git for repository state:

1. Branch detection: Uses git branch --show-current to identify the active development branch areal/version.py63-71
2. Commit hash: Uses git rev-parse --short HEAD to get the unique identifier for the current code state areal/version.py72-80
3. Dirty status: Uses git diff-index --quiet HEAD -- which returns a non-zero exit code if uncommitted changes exist areal/version.py81-86

All subprocess calls are executed with cwd=Path(__file__).parent to ensure they target the AReaL repository even if the script is invoked from elsewhere areal/version.py67-84

Caching Strategy

The _populate_version_info() method is decorated with @lru_cache(maxsize=1) areal/version.py60 This ensures that the relatively expensive subprocess calls are executed only once per process lifetime, providing a stable version snapshot for the duration of the training or inference run.

Sources: areal/version.py60-86

Version String Formats

AReaL provides multiple version string formats for different use cases:

Full Version Computation

The full_version property combines the semantic version, commit hash, and dirty status into a single string for logging and checkpointing areal/version.py43-49

Repository State	full_version Output
Clean, tagged release	"1.0.4"
Clean, development state	"1.0.4-abc1234"
Uncommitted changes	"1.0.4-abc1234-dirty"

Dirty State Description

The full_version_with_dirty_description property provides a human-readable warning when uncommitted changes are present areal/version.py52-58 This is particularly useful for production runs where code consistency is critical.

Sources: areal/version.py42-58

Release Workflow and Docker Tagging

Build and Push Pipeline

The release workflow defined in .github/workflows/tag-release-image.yml automates the creation of versioned Docker images when a GitHub release is created or a manual dispatch is triggered with a specific tag .github/workflows/tag-release-image.yml1-12

Title: Automated Release Image Tagging Flow

Sources: .github/workflows/tag-release-image.yml1-195

Multi-Variant Tagging

AReaL builds multiple variants of the runtime image to support different inference backends. The workflow tags these images according to the version extracted from pyproject.toml and the backend variant .github/workflows/tag-release-image.yml164-182

The Dockerfile handles these variants via the VARIANT build argument, pinning different base images and dependencies for SGLang and vLLM variants .github/workflows/tag-release-image.yml168-181

Image Tag	Backend	Source Version
v1.0.4-sglang	SGLang	pyproject.toml
v1.0.4-vllm	vLLM	pyproject.toml
latest	SGLang (Default)	pyproject.toml

Sources: .github/workflows/tag-release-image.yml164-182

Docker Image Versioning in Configuration

Versioned Docker images are referenced throughout the project's deployment configurations to ensure environment parity.

• SkyPilot Single Node: References ghcr.io/inclusionai/areal-runtime:v1.0.4-sglang examples/skypilot/single_node.sky.yaml11
• SkyPilot Ray Cluster: References ghcr.io/inclusionai/areal-runtime:v1.0.4-sglang examples/skypilot/ray_cluster.sky.yaml4

Sources: examples/skypilot/single_node.sky.yaml11 examples/skypilot/ray_cluster.sky.yaml4

Module-Level Interface

For ease of use, the areal/version.py module exports a singleton version_info instance and several top-level attributes for backward compatibility areal/version.py91-97

Sources: areal/version.py91-97