# Publishing to PyPI

This project uses GitHub Actions to automatically publish to PyPI when a version tag is pushed.

## Prerequisites

1. **PyPI Account**: Ensure you have a PyPI account at https://pypi.org

2. **Trusted Publishing Setup**: Configure trusted publishing in your PyPI project settings:
   - Go to your PyPI project settings
   - Navigate to "Publishing" → "Add a pending publisher"
   - Select "GitHub" as the publisher
   - Enter your GitHub repository (e.g., `username/payelink-agent-pay-sdk`)
   - Select the workflow file: `.github/workflows/publish-pypi.yml`
   - Add the publisher

3. **GitHub Environment**: Ensure a GitHub environment named `pypi` exists in your repository:
   - Go to repository Settings → Environments
   - Create an environment named `pypi` (if it doesn't exist)
   - No additional configuration needed for trusted publishing

## Publishing a New Version

1. **Update version files** (optional - workflow will update automatically):
   - The workflow automatically extracts the version from the git tag
   - Version format should be semantic: `v0.1.0`, `v1.2.3`, etc.

2. **Create and push a version tag**:
   ```bash
   # Create an annotated tag
   git tag -a v0.1.0 -m "Release version 0.1.0"
   
   # Push the tag to trigger the workflow
   git push origin v0.1.0
   ```

3. **Monitor the workflow**:
   - Go to the "Actions" tab in your GitHub repository
   - The "Publish to PyPI" workflow will run automatically
   - The workflow will:
     - Extract version from tag (e.g., `v0.1.0` → `0.1.0`)
     - Update `pyproject.toml` and `_version.py` with the extracted version
     - Build the package (wheel and source distribution)
     - Publish to PyPI using trusted publishing

## Workflow Details

- **Trigger**: Pushes to tags matching pattern `v*` (e.g., `v0.1.0`, `v1.2.3`)
- **Version Extraction**: Automatically removes the `v` prefix from the tag
- **Build System**: Uses `hatchling` as configured in `pyproject.toml`
- **Publishing**: Uses PyPI trusted publishing (no API tokens needed)

## Troubleshooting

- **Workflow fails with authentication error**: Verify trusted publishing is configured correctly in PyPI
- **Version not updating**: Ensure tag follows semantic versioning format (`v0.1.0`, not `0.1.0`)
- **Build fails**: Check that `pyproject.toml` is correctly configured and all dependencies are available
- **Package name conflict**: Ensure the package name in `pyproject.toml` matches your PyPI project name
