Set up PyPI publishing workflow (Trusted Publishing) + release process

[eeholmes]

Title: Set up PyPI publishing workflow (Trusted Publishing) + release process

Goal

Automate publishing this package to PyPI when we create a GitHub Release (tagged version). Prefer PyPI Trusted Publishing (OIDC) using pypa/gh-action-pypi-publish so we don’t store PyPI tokens in GitHub Secrets.

Tasks

Confirm packaging is ready

Ensure we have a working pyproject.toml with correct metadata:

[project].name point-collocation

version is set

readme / license / requires-python, etc.

Ensure src/ layout imports work (e.g., import point_collocation).

Add a publish workflow
Create .github/workflows/publish.yml that:

Triggers on release: { types: [published] }

Builds sdist + wheel using python -m build

Publishes using pypa/gh-action-pypi-publish@release/v1

Uses Trusted Publishing permissions:

permissions: id-token: write

contents: read

Include a small “smoke check” step that installs the built wheel locally and imports the package.

Reference docs:

Packaging guide for publishing from GitHub Actions

gh-action-pypi-publish trusted publishing requirements

PyPI trusted publisher usage docs

Document the release steps
Update README.md (or add docs/releasing.md) with:

how to bump version

how to create a tag / GitHub Release

what triggers publishing

troubleshooting tips (common errors: missing trusted publisher, version already exists, metadata issues)

Acceptance criteria

A GitHub Release publishes a wheel + sdist to PyPI successfully.

Workflow uses Trusted Publishing (OIDC) with id-token: write and no stored PyPI token.

Documentation exists describing the release/publish process.

[eeholmes]

Repo secrets you need to create
Preferred (Trusted Publishing)

None.
With Trusted Publishing, you do not store a PyPI API token in GitHub Secrets. Instead, you configure a Trusted Publisher on PyPI that trusts this GitHub repo + workflow.

What you do need to configure (on PyPI, not GitHub):

PyPI project → Settings → Trusted Publishers

Add GitHub as publisher and specify:

owner/org

repo name

workflow file path (e.g. .github/workflows/publish.yml)

environment (if you choose to use one)

(Your agent can add the workflow, but you’ll still need to click through PyPI once to register the trusted publisher.)