PyPI Release Checklist¶

First-Time Setup (One-Time)¶

1. Create a PyPI account at pypi.org if you don't have one.

2. Go to your PyPI account > Publishing > Add a new pending publisher.

3. Fill in the form:

4. PyPI Project Name: Your package name (e.g., my-package)
5. Owner: Your GitHub username or organization
6. Repository name: Your repo name
7. Workflow name: publish.yml

8. Environment name: pypi

9. In your GitHub repo, go to Settings > Environments > New environment. Name it pypi. Optionally add required reviewers and restrict deployment to v* tags.

10. Push your first tag to trigger the publish (see below).

Every Release¶

1. Write your release notes in CHANGELOG/vX.Y.Z.md and commit:

   git add CHANGELOG/
   git commit -m "Add release notes for vX.Y.Z"
   

2. Bump the version and commit:

   uv version patch  # or: minor, major
   git add pyproject.toml uv.lock
   git commit -m "Bump version to X.Y.Z"
   

3. Push, then tag and push the tag:

   git push
   just tag
   

4. GitHub Actions builds, signs with Sigstore, and publishes to PyPI automatically.

Troubleshooting¶

If the publish fails:

• Check that your PyPI trusted publisher settings match your workflow exactly
• Verify the tag format matches what PyPI expects (e.g., v1.0.0)
• Look at the GitHub Actions logs for detailed error messages