Shipping & Releases
Relevant source files
The following files were used as context for generating this wiki page:
Shipping and Releases in the FLEXT workspace represent the final stages of the development lifecycle, encompassing automated pull request (PR) creation, version tagging, and production-ready releases. This system is governed by a strict "Continuous Green" policy, ensuring that no completion or promotion occurs while the environment is broken or missing real-use validation. The workspace utilizes a canonical command surface for all release actions, primarily driven by the make ship verb and its associated subcommands.
Sources: AGENTS.md:37-43, scripts/tests/test_registry_contract.py:168-180
Release Governance and Standards
The FLEXT project operates under a "land-immediately" profile for verified changes. Developers are authorized to perform scoped git add, git commit, and fast-forward git push actions. However, promotion to main and formal releases are strictly managed by an orchestrator role rather than individual workers.
Governance Rules for Shipping
- No Red Pushes: No completion is permitted while the project or environment is broken. All changes must pass linting (Ruff, Pyrefly), type checking (Pyright, Mypy), and unit tests.
- Separated Roles: Workers implement one "Bead" in a branch but never merge or promote
main. The orchestrator coordinates, validates, and approves merges. - Version Tagging: Releases require explicit tagging and promotion, often routed through private Make targets like
_relor_tag.
Sources: AGENTS.md:43-52, AGENTS.md:129-132, scripts/tests/test_registry_contract.py:168-175
Command Architecture
The shipping system is implemented as a registry-driven dispatcher. The ship verb contains multiple subcommands (WHAT parameters) that handle different aspects of the release process.
Ship Command Registry
| Command | Parameter (WHAT) | Target/Implementation | Description |
|---|---|---|---|
ship | all | _rel | The default release command. |
ship | rel | _rel | Formal release promotion. |
ship | pr | _pr | Pull Request creation and coordination. |
ship | tag | _tag | Version tagging (requires TAG env). |
ship | push | _push | Pushing verified changes to remote. |
ship | save | scripts.cmd.ship.save | Direct Python implementation for saving state. |
Sources: scripts/tests/test_registry_contract.py:168-180, scripts/tests/test_registry_contract.py:186-200
Execution Flow for Release Commands
The following diagram illustrates how the Dispatch system routes release commands from the Make surface to internal implementations:
Pull Request Management
The project utilizes automated workflows for PR management, particularly for dependency updates and workspace coordination.
Automated Dependency Merging
The dependabot_merge.py script automates the merging of Dependabot PRs across the workspace submodules. It enforces a conventional commit schema: chore(deps): bump <package> <old> → <new> [<ecosystem>].
Release Metadata and Versioning
Release versions are managed in the pyproject.toml and localized libs/versioning.py utilities. The workspace follows Semantic Versioning (SemVer) and maintains a dev-branch status (e.g., 0.12.0-dev).
Versioning Implementation
- Workspace Version: Tracked in
project.versionwithinpyproject.toml. - Lazy Exports: The
libspackage utilizesinstall_lazy_exportsto manage versioning utilities likebump_version,parse_semver, andreplace_project_versionwithout eager loading.
Sources: pyproject.toml:34, libs/init.py:1-40
Mutation Control
Critical release actions that modify the repository state (mutating commands) require an explicit opt-in through the APPLY=Y parameter. This prevents accidental releases during dry runs.
# From scripts/tests/test_registry_contract.py:53-65
def test_all_mutating_commands_declare_required_apply(
registry: Dispatch.Registry,
) -> None:
"""Assert every mutating command exposes the dispatcher mutation opt-in."""
for verb in u.Tests.make_registry_verbs(registry):
commands = u.Tests.make_registry_commands(registry, verb).unwrap()
for command in commands.values():
if not command.mutates:
continue
apply_param = next(
(param for param in command.params if param.name == c.Tests.MAKE_APPLY_PARAM),
None,
)
assert apply_param is not None
assert apply_param.required is True
Sources: scripts/tests/test_registry_contract.py:53-76, scripts/tests/test_registry_contract.py:155-165
Shipping and Releases in FLEXT are high-stakes operations requiring strict technical compliance. By enforcing role separation, mandatory "Green" gates, and explicit mutation opt-ins, the project ensures that formal releases maintain the architectural integrity defined in the project governance.