Release Orchestration DAG
Relevant source files
The following files were used as context for generating this wiki page:
The Release Orchestration DAG (Directed Acyclic Graph) is a structured workflow system within the flext-infra package designed to manage the end-to-end lifecycle of software releases across a workspace. It automates critical tasks such as version bumping, project building, validation, and publishing to ensure consistency across multiple projects within the FLEXT ecosystem.
Sources: src/flext_infra/release/orchestrator.py:21-25, src/flext_infra/release/_orchestrator_dispatch.py:90-110
Architecture and Design
The system is built using a mixin-based architecture centered around the FlextInfraReleaseOrchestrator. It leverages a pipeline-based execution model where release phases are treated as discrete stages in a linear sequence.
Core Components
| Component | Responsibility |
|---|---|
FlextInfraReleaseOrchestrator | The primary service class coordinating the release lifecycle. |
FlextInfraReleaseOrchestratorDispatchMixin | Handles the routing of phases and the high-level pipeline execution logic. |
FlextInfraReleaseOrchestratorPhases | Contains the implementation details for the Build and Version phases. |
FlextInfraReleaseOrchestratorPublishMixin | Manages the specific logic for publishing, including tagging and changelog updates. |
Sources: src/flext_infra/release/orchestrator.py:21-27, src/flext_infra/release/_orchestrator_dispatch.py:19-21, src/flext_infra/release/orchestrator_phases.py:24-27, src/flext_infra/release/_orchestrator_publish.py:20-22
Execution Flow
The following diagram illustrates the high-level orchestration flow from initialization to completion.
The flow begins by resolving the target version (either via explicit arguments or interactive bumping) and then dispatches the specific phases requested in the configuration.
Sources: src/flext_infra/release/_orchestrator_dispatch.py:168-190, src/flext_infra/release/_orchestrator_dispatch.py:108-140
Release Phases
The orchestrator executes four canonical phases in a strictly defined order. While users can select specific phases, the internal logic ensures they run according to the system's dependency requirements.
Phase: Validate
Executes workspace-level validation checks (e.g., make val) to ensure the codebase meets quality standards before proceeding with a release.
Sources: src/flext_infra/release/_orchestrator_dispatch.py:213-228
Phase: Version
Updates the version string across all targeted pyproject.toml files in the workspace and individual projects. It uses regex-based replacement to maintain version consistency.
Sources: src/flext_infra/release/orchestrator_phases.py:97-111, src/flext_infra/release/orchestrator.py:75-87
Phase: Build
Invokes the make build command for the workspace root and every selected project. It generates a build-report.json containing exit codes and log paths for each project.
Sources: src/flext_infra/release/orchestrator_phases.py:38-95
Phase: Publish
Finalizes the release by:
- Generating
RELEASE_NOTES.mdfrom git history and project lists. - Updating
CHANGELOG.mdand creating release snapshots indocs/releases/. - Creating an annotated Git tag.
- Optionally pushing the branch and tag to the remote origin.
Sources: src/flext_infra/release/_orchestrator_publish.py:35-65, src/flext_infra/_utilities/release.py:65-95
Data Models and Configuration
The system uses Pydantic-based models to enforce strict typing and validation for release metadata.
ReleaseOrchestratorConfig
This model defines the parameters for a full release run.
| Field | Type | Default | Description |
|---|---|---|---|
workspace_root | Path | Required | The root directory of the workspace. |
version | str | Required | The target semantic version. |
tag | str | Required | The Git tag (e.g., v1.0.0). |
phases | StrSequence | Required | Ordered list of phases to execute. |
dry_run | bool | False | If true, skips filesystem writes and git operations. |
push | bool | False | Whether to push to the remote repository. |
next_dev | bool | False | Whether to bump to the next dev version after release. |
Sources: src/flext_infra/_models/release.py:53-65
Build Reporting Structure
During the build phase, the orchestrator aggregates results into a structured JSON report.
Key Implementation Details
Version Resolution
The orchestrator supports both manual version entry and semantic bumping (major, minor, patch). If no version is provided and interactive mode is enabled, it prompts the user for a bump type.
Sources: src/flext_infra/release/_orchestrator_dispatch.py:69-83
Target Discovery
Build and Version phases dynamically resolve targets. The workspace root is always included, followed by projects discovered via u.Infra.resolve_projects based on the provided project selectors.
Sources: src/flext_infra/release/orchestrator.py:53-73
Changelog Management
The FlextInfraUtilitiesRelease class handles the idempotent insertion of new release sections into CHANGELOG.md. It uses a standard marker (# Changelog) to find the insertion point and ensures that the same version is not added multiple times.
Sources: src/flext_infra/_utilities/release.py:127-142
Summary
The Release Orchestration DAG provides a robust, predictable framework for deploying FLEXT infrastructure. By codifying the release steps into a pipeline and using centralized models for version and build metadata, it reduces the risk of manual errors and ensures that all projects in a workspace remain synchronized during the release cycle.