# Publishing gconcord to PyPI

This guide explains how to publish gconcord to PyPI.

## Prerequisites

1. PyPI account at https://pypi.org/
2. Package name "gconcord" available (or choose different name)
3. GitHub repository with proper workflows

## Method 1: GitHub Actions with Trusted Publishing (Recommended)

### Step 1: Configure PyPI Trusted Publishing

1. Go to https://pypi.org/manage/account/publishing/
2. Add a new trusted publisher:
   - PyPI Project Name: `gconcord`
   - Owner: `your-github-username`
   - Repository name: `gconcord`
   - Workflow name: `publish.yml`
   - Environment name: `pypi` (optional but recommended)

### Step 2: Create GitHub Environment (Optional but recommended)

1. Go to Settings → Environments in your GitHub repo
2. Create environment named `pypi`
3. Add protection rules:
   - Required reviewers (optional)
   - Restrict to protected branches

### Step 3: Create a Release

```bash
# Update version in pyproject.toml and __init__.py
# Commit changes
git add pyproject.toml gconcord/__init__.py
git commit -m "Bump version to 1.0.2"
git push

# Create and push tag
git tag v1.0.2
git push origin v1.0.2
```

4. Go to GitHub → Releases → "Create a new release"
5. Choose your tag, add release notes
6. Click "Publish release"

The workflow will automatically build and upload to PyPI!

## Method 2: API Token

### Step 1: Create PyPI API Token

1. Go to https://pypi.org/manage/account/token/
2. Create token with scope for "gconcord" project
3. Copy the token (starts with `pypi-`)

### Step 2: Add to GitHub Secrets

1. Go to Settings → Secrets → Actions in your repo
2. Add new secret named `PYPI_API_TOKEN`
3. Paste your token value

### Step 3: Update workflow if needed

The publish.yml already supports token-based auth as fallback.

## Method 3: Manual Publishing

### Build all wheels locally

```bash
# Install build tools
pip install build cibuildwheel twine

# Build source distribution
python -m build --sdist

# Build wheels (current platform only)
cibuildwheel --platform auto

# Or use Docker to build Linux wheels on Mac
CIBW_PLATFORM=linux cibuildwheel
```

### Upload to PyPI

```bash
# Test on Test PyPI first
twine upload --repository testpypi dist/* wheelhouse/*

# Upload to production PyPI
twine upload dist/* wheelhouse/*
```

## Verifying the Release

After publishing:

```bash
# Wait a few minutes for PyPI to update
pip install gconcord

# Test import
python -c "import gconcord; print(gconcord.__version__)"
```

## Platform Support

The package will be available for:
- **Linux**: Python 3.8-3.12 on x86_64
- **macOS**: Python 3.7-3.12 on x86_64 and arm64

Users on other platforms can install from source:
```bash
pip install gconcord --no-binary :all:
```

## Troubleshooting

### "Trusted publishing not configured"
- Ensure the workflow name matches exactly
- Check environment name if using one
- Wait a few minutes after configuring

### "Version already exists"
- Bump version in pyproject.toml and __init__.py
- PyPI doesn't allow overwriting versions

### "Missing wheels for platform"
- Check GitHub Actions logs
- Ensure all workflow jobs completed
- Linux aarch64 not supported (by design)