Skip to main content

Releasing persisting

Stable releases are built by GitHub Actions from version tags and published to PyPI with Trusted Publishing. The project still ships as a Python wheel, but it does not contain a PyO3 extension and does not use Maturin.

Each platform wheel is tagged py3-none-<platform> and contains:

  • the Python persisting package;
  • native command-line scripts;
  • the bundled pChronicle Web assets;
  • the platform libkrun firmware payload required by pVisor.

The release set currently contains Linux x86_64 and Apple Silicon macOS wheels. Source distributions are not part of the published artifact set.

One-time setup​

  1. Create a GitHub environment named pypi. Do not require reviewers; restrict deployments to tags matching v*.
  2. In the PyPI publishing settings, add a pending Trusted Publisher:
    • PyPI project: persisting
    • GitHub owner: DeepLink-org
    • Repository: Persisting
    • Workflow: release.yml
    • Environment: pypi

No PyPI API token is stored in GitHub. The pending publisher can create the project during the first successful upload but does not reserve the name.

Prepare a release​

  1. Update the same X.Y.Z version in pyproject.toml, the workspace package section of Cargo.toml, and persisting/__init__.py.

  2. Refresh local workspace versions in the lockfile without upgrading dependencies:

    cargo metadata --format-version 1 --no-deps >/dev/null

  3. Commit and merge the version change to main. The workflow refuses a tag whose commit is not reachable from main.

  4. Optionally run Publish PyPI manually. A manual run builds and verifies all wheels but does not publish them.

  5. Create and push the matching stable tag:

    git tag vX.Y.Z
    git push origin vX.Y.Z

Build and verification path​

The PEP 517 backend is setuptools with the repository-owned scripts/packaging/build_backend.py. Before wheel assembly it builds the three Rust CLIs, stages firmware, and ensures the Dioxus bundle exists. setup.py marks the wheel platform-specific while keeping the Python and ABI tags py3-none.

The packaging script fetches the pinned libkrun firmware archive for both Linux x86_64 and Apple Silicon macOS unless PERSISTING_LIBKRUNFW_PATH points at an existing payload. Local wheel builds must use one of those supported paths; a missing payload is a build error rather than an incomplete wheel.

Linux wheels use the manylinux_2_28 / glibc 2.28 tag. Current rustc libstd and libkrun's virtiofs passthrough need statx and copy_file_range, which are not available on manylinux2014.

Every wheel is checked for its component set and install-time CLI smoke tests. The release-set check then requires exactly one supported wheel per platform, matching versions, valid package metadata, and bounded artifact size before publishing.

Re-running a partially completed tagged release skips files PyPI already accepted and repairs missing GitHub Release assets.