ADR-10: Cross-repo release train

Status: accepted (2026-05-28) Blocks: workstream C (release process), workstream D (Python packaging).

Context

dag-ml depends on dag-ml-data; nirs4all depends on dag-ml + dag-ml-data (eventually). Without a scripted release order, version pinning drifts (Codex flagged this as the “cross-repo release coordination” risk).

Decision

The release train is a fixed five-step sequence, scripted and CI-gated:

  1. dag-ml-data releases first. cargo-release cuts a tag, publishes the four dag-ml-data-* crates to crates.io, builds and uploads the Python wheel (dag-ml-data-py) to PyPI, and runs the cross-header parity test against dag-ml at HEAD.

  2. dag-ml’s pinned dag-ml-data version bumps. A scripted PR (opened by the release workflow) updates the workspace Cargo.toml’s dag-ml-data = { version = "X.Y.Z" } constraint, runs the green gate, and merges automatically if the gate is green.

  3. dag-ml releases. Same scripted path: cargo-release → crates.io for the four dag-ml-* crates → PyPI wheel for dag-ml-py → CHANGELOG entry referencing ADR-10.

  4. nirs4all’s pinned dag-ml + dag-ml-data versions bump. Same scripted-PR pattern; nirs4all’s CI gates on dag-ml ≥ X.Y.Z AND dag-ml-data ≥ X.Y.Z.

  5. nirs4all releases (independent cadence; usually one release per train run).

CI gates

  • Each release tag triggers release-crates.yml in the repo being released. The workflow validates release metadata, validates the Cargo publish plan, checks that the v* tag matches the workspace version and publishes crates in dependency order.

  • release-crates.yml accepts final SemVer tags such as v0.2.0 and still supports prerelease SemVer tags for future alpha/beta/rc trains when explicitly needed.

  • cargo publish --dry-run runs in CI through scripts/release/check_publish_plan.py --dry-run.

  • A “release ready” PR check verifies CHANGELOG, ADR delta, and ABI snapshot are present.

Hotfix path

For a single-repo hotfix (e.g. dag-ml only, leaving dag-ml-data unchanged), the release script accepts --skip-data and runs steps 3–5 directly. The CHANGELOG entry must justify the skip.

Consequences

  • scripts/release/ lands in both repos with per-repo release-crates.yml GitHub Actions workflows for crates.io publication.

  • CONTRIBUTING.md documents the train and the hotfix exception.

  • Version pinning becomes a hard CI constraint; manual edits are reverted by the bot.

Risk

  • A breaking change in dag-ml-data that dag-ml cannot adopt blocks the whole train. The release script surfaces this with a clear “dag-ml does not compile against dag-ml-data X.Y.Z” error and refuses to proceed. Resolution: either revert the breaking change or land the dag-ml-side migration first.