# Publishing Guide

This project uses a `pyproject.toml` package configuration and can be published with `build` + `twine`.

## 1. Prerequisites
- PyPI account: https://pypi.org
- (Optional) TestPyPI account: https://test.pypi.org
- API tokens created in account settings.

## 2. Install release tooling
```bash
python -m pip install --upgrade build twine
```

## 3. Bump version
Update both:
- `pyproject.toml` -> `[project].version`
- `gaunt/__init__.py` -> `__version__`

Use semantic versioning:
- Patch: `0.1.0 -> 0.1.1` for fixes
- Minor: `0.1.0 -> 0.2.0` for backwards-compatible features
- Major: `0.1.0 -> 1.0.0` for breaking changes

## 4. Run tests
```bash
pytest -q
```

## 5. Build distributions
```bash
python -m build
```

This creates:
- `dist/*.whl`
- `dist/*.tar.gz`

## 6. Upload to TestPyPI (recommended first)
```bash
python -m twine upload --repository testpypi dist/*
```

Install from TestPyPI to verify:
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple gaunt
```

## 7. Upload to PyPI
```bash
python -m twine upload dist/*
```

## 8. Tag the release in git
```bash
git tag v0.1.0
git push origin v0.1.0
```

## Optional: `.pypirc`
You can configure repository aliases in `~/.pypirc`:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-...
```
