Skip to content

Cut the first release: publish magnetics to PyPI #91

Description

@matt-pharr

Goal

Publish magnetics to PyPI so the app is installable with uvx magnetics /
pip install magnetics, and so magnetics-connect's zero-install bootstrap
works on a fresh machine with nothing but the launcher.

Everything downstream is already built and waiting on this:

  • magnetics-connect (PR connect: run the GUI on a cluster node, browse it locally (magnetics-connect) #89) bootstraps a remote by running uvx magnetics
    when no install is present — today it falls back to an existing install or
    --install-from <wheel> as a shim, because PyPI has nothing yet (pypi.org/pypi/magnetics → 404).
  • The Release workflow (.github/workflows/release.yml) already builds the
    GUI-bundled wheel + sdist, smoke-tests the install in a clean venv, publishes
    to PyPI via Trusted Publishing (OIDC, no token), and creates a GitHub
    Release with the artifacts attached.
  • docs/RELEASING.md documents the whole process.

So this issue is about doing the one-time publisher setup and cutting the
first tagged release — not writing new code.

One-time setup (before the first tag)

Per docs/RELEASING.md:

  1. Register the pending publisher on PyPI (reserves the currently-unclaimed
    magnetics name). PyPI → Account → Publishing → Add a pending publisher:
    • PyPI project name: magnetics
    • Owner: OpenFUSIONToolkit
    • Repository: Magnetics
    • Workflow: release.yml
    • Environment: pypi
  2. Create the pypi GitHub environment (repo Settings → Environments), name
    matching the workflow. Optionally require a reviewer to approve each publish.

The pending publisher must exist before the first tag push or the publish step
fails auth (harmlessly — finish setup and re-run).

Cutting the release (GitFlow-lite)

  1. Branch off develop, bump version in pyproject.toml (keep
    src/magnetics/__init__.py:__version__ in step). PR into develop.
  2. Release PR developmain, merge.
  3. Tag the merge commit on main (vX.Y.Z, must match pyproject.toml) and push
    the tag. The Release workflow builds, smoke-tests, publishes, and creates the
    GitHub Release.

Tip: gh workflow run release.yml (workflow_dispatch) does the build + smoke test
without publishing — a safe dry run of GUI bundling / wheel install / launcher boot.

Acceptance

  • uvx magnetics boots the GUI on a clean machine (no checkout).
  • python3 connect.py <host> on a host with no prior install bootstraps
    via uvx magnetics end-to-end (the fresh-node GA path).
  • A GitHub Release exists with the wheel + sdist attached.

Follow-ups once published

  • Drop the --install-from shim guidance from the magnetics-connect docs (the
    PyPI default just works).
  • Consider an Lmod module on omega that wraps uvx magnetics for GA users who
    prefer module load magnetics.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions