# Release Guide

This project is prepared for `v0.1.0` style releases.

## 1. Pre-release Checks

Run local checks:

```bash
./scripts/release_check.sh
```

The script runs:
- compile check
- test suite
- wheel build

## 2. Version Bump

Recommended:

```bash
python3 scripts/bump_version.py 0.1.1
```

This updates:
- `pyproject.toml` -> `[project].version`
- `exile/__init__.py` -> `__version__`
- `CHANGELOG.md` -> scaffolds release section if missing

## 3. Build Artifacts

```bash
python3 -m pip install --upgrade build
python3 -m build
```

Expected outputs in `dist/`:
- `<distribution_name>-<version>-py3-none-any.whl`
- `<distribution_name>-<version>.tar.gz`

## 4. Validate Artifacts

```bash
python3 -m pip install --upgrade twine
python3 -m twine check dist/*
```

The local release checker also verifies version consistency:

```bash
python3 scripts/check_version_sync.py
python3 scripts/check_changelog_version.py
python3 scripts/check_changelog_content.py
python3 scripts/check_dist_artifacts.py
python3 scripts/smoke_test_wheel.py
```

## 5. Publish To TestPyPI (Recommended Dry Run)

```bash
./scripts/check_worktree_clean.sh
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="<your-testpypi-token>"
./scripts/publish_testpypi.sh
```

Equivalent command:

```bash
TWINE_REPOSITORY=testpypi ./scripts/publish_pypi.sh
```

If you intentionally publish from a dirty working tree:

```bash
ALLOW_DIRTY=1 TWINE_REPOSITORY=testpypi ./scripts/publish_pypi.sh
```

## 6. Publish To PyPI (Manual)

Use API token:

```bash
./scripts/check_worktree_clean.sh
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="<your-pypi-token>"
./scripts/publish_pypi.sh
```

If you intentionally publish from a dirty working tree, set:

```bash
ALLOW_DIRTY=1 ./scripts/publish_pypi.sh
```

Or direct upload:

```bash
python3 -m twine upload --repository pypi dist/*
```

## 7. Publish Via GitHub Actions (Recommended)

The workflow `.github/workflows/publish.yml` publishes when a version tag is pushed:
- example tag: `v0.1.0`
- tag is validated against `pyproject.toml` version before publish
- workflow runs version/changelog checks, test suite, build, and `twine check` before publish

```bash
git tag v0.1.0
git push origin v0.1.0
```

If trusted publishing is configured in PyPI, no API token secret is required.
