Skip to content

python-sdk: fat-wheel packaging — maturin abi3 build matrix in the release pipeline #282

Description

@rahlk

PROBLEM

cldk today ships as a pure-Python wheel from a single-runner release workflow. With the Rust core in-tree (fat-wheel decision), the release must build maturin/PyO3 abi3 platform wheels — a per-platform build matrix — while keeping the tag-triggered pipeline's guarantees (test-gate → delete tag on failure → PyPI → release → announcements → docs dispatch).

SCOPE BOUNDARY

Release/packaging/verify only — no engine features. Docs content is the docs-repo child; this issue only wires the docs dispatch as before.

GOALS (the contract, as a checklist)

  1. pyproject.toml moves to maturin as build backend; abi3 wheels covering the SDK's supported Python range (3.11+).
  2. Release workflow: build matrix (linux x86_64/aarch64 incl. manylinux repair, macOS x86_64/arm64, Windows x86_64) fanning into one publish job; per-artifact SHA256.
  3. Smoke-test every wheel on a clean runner before publish (import cldk + run one fluent query against a fixture).
  4. Tag-gate semantics preserved: suite green before any publish; tag deleted on failure.
  5. sdist ships with a clear "requires a Rust toolchain" build path (documented), never a silent broken fallback.
  6. CHANGELOG + README architecture note (build strategy per packaging-and-release.md convention).

CAVEATS AND KNOWN RISKS

  • Platforms without a prebuilt wheel lose trivial pip install — accepted in the fat-wheel decision; document loudly.
  • CI wall-clock will grow substantially (matrix × cargo build); cache cargo aggressively.
  • abi3 forgetting a symbol pin is a silent per-version break — enforce abi3 audit in CI.

DEFINITION OF DONE

  • A tagged rc from this branch publishes wheels for every matrix platform; pip install + fluent-query smoke passes on each in CI.
  • Existing release side-effects (GitHub Release, announcements, docs dispatch) intact.

Part of #279

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions