Implement GitHub Action to package and publish regshape to PyPI

[toddysm]

Summary

Implement a GitHub Actions workflow that builds, packages, and publishes the regshape Python package to PyPI on tagged releases.

Steps to Implement

1. Create a PyPI Account and API Token

• Create an account on PyPI (and optionally TestPyPI for testing).
• Generate an API token scoped to the regshape project (or account-wide for the first upload).
• Store the token as a GitHub repository secret named PYPI_API_TOKEN.

2. Configure Trusted Publishing (Recommended)

• Instead of using API tokens, configure PyPI Trusted Publishing for GitHub Actions.
• On PyPI, add a new "pending publisher" with:
  • Owner: toddysm
  • Repository: regshape
  • Workflow name: publish.yml
  • Environment name: pypi (or as chosen)
• This eliminates the need to manage API tokens as secrets.

3. Create the GitHub Actions Workflow File

• Create .github/workflows/publish.yml with the following stages:

Build Stage

• Trigger on tagged releases (e.g., v*.*.* tags) or GitHub release events.
• Check out the repository.
• Set up Python (3.10+).
• Install build dependencies: pip install build.
• Build the sdist and wheel: python -m build.
• Upload the built artifacts using actions/upload-artifact.

Publish Stage

• Depends on the build stage completing successfully.
• Use a dedicated GitHub environment (e.g., pypi) with optional approval rules.
• Use pypa/gh-action-pypi-publish@release/v1 to publish to PyPI.
• If using trusted publishing, set id-token: write permission instead of passing tokens.

4. Validate pyproject.toml Metadata

• Ensure all required PyPI metadata is present in pyproject.toml:
  • name ✅
  • version ✅
  • description ✅
  • readme ✅
  • requires-python ✅
  • license ✅
  • Add authors field
  • Add classifiers (e.g., Development Status, License, Programming Language, OS)
  • Add project.urls (Homepage, Repository, Bug Tracker)

5. Add a TestPyPI Workflow (Optional but Recommended)

• Create a separate workflow or job that publishes to TestPyPI on pre-release tags or manual dispatch.
• Use repository-url: https://test.pypi.org/legacy/ in the publish action.
• Verify the package installs correctly from TestPyPI before publishing to production.

6. Add Version Validation

• Ensure the version in pyproject.toml matches the Git tag triggering the workflow.
• Optionally add a step that extracts the tag version and compares it against the package version to prevent mismatches.

7. Add Build Verification

• After building, run twine check dist/* to validate the package metadata and distribution files.
• Install twine as a build dependency for this check.

8. Update Documentation

• Add a "Releasing" section to CONTRIBUTING.md documenting:
  • How to create a release (tag naming convention, GitHub Releases).
  • The automated publish workflow and what it does.
  • How to verify the published package.

Example Workflow Structure

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ">=3.10"
      - run: pip install build twine
      - run: python -m build
      - run: twine check dist/*
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  publish:
    needs: build
    runs-on: ubuntu-latest
    environment: pypi
    permissions:
      id-token: write
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - uses: pypa/gh-action-pypi-publish@release/v1

Acceptance Criteria

• GitHub Actions workflow triggers on release publish events.
• Package builds successfully as sdist and wheel.
• Package is published to PyPI automatically.
• pyproject.toml has complete metadata for PyPI.
• Trusted publishing is configured (preferred) or API token is stored securely.
• Build artifacts are verified with twine check before publishing.
• Release process is documented in CONTRIBUTING.md.