# Release Instructions

## Test Release (TestPyPI)

Use this to verify the publish workflow before a production release.

### 1. Update version and docs

```bash
# Update version in source
# Edit src/unfamiliar/__init__.py: __version__ = "0.1.0"

# Update CHANGELOG.md
# Move items from [Unreleased] to [0.1.0] - YYYY-MM-DD
```

### 2. Commit and tag (private repo)

```bash
git add .
git commit -m "Release v0.1.0-rc1"
git tag v0.1.0-rc1
git push origin main
git push origin v0.1.0-rc1
```

### 3. Push to public repo

```bash
scripts/push-public.sh v0.1.0-rc1
```

This triggers `publish-test.yml` → publishes to TestPyPI.

### 4. Verify

- Check GitHub Actions tab in public repo for workflow success
- Check https://test.pypi.org/project/unfamiliar/

### 5. Test install from TestPyPI

```bash
pip install --index-url https://test.pypi.org/simple/ unfamiliar
```

---

## Production Release (PyPI)

### 1. Finalize version and docs

```bash
# Ensure version is final (no -rc suffix)
# Edit src/unfamiliar/__init__.py: __version__ = "0.1.0"

# Ensure CHANGELOG.md has the release date filled in
# [0.1.0] - 2024-01-15
```

### 2. Commit and tag (private repo)

```bash
git add .
git commit -m "Release v0.1.0"
git tag v0.1.0
git push origin main
git push origin v0.1.0
```

### 3. Push to public repo

```bash
scripts/push-public.sh v0.1.0
```

This triggers `publish.yml` → publishes to production PyPI.

### 4. Verify

- Check GitHub Actions tab in public repo for workflow success
- Check https://pypi.org/project/unfamiliar/

### 5. Create GitHub Release

1. Go to public repo → Releases → "Draft a new release"
2. Select tag: `v0.1.0`
3. Title: `v0.1.0 — Initial Release`
4. Body: paste relevant section from CHANGELOG.md
5. Publish

### 6. Test install from PyPI

```bash
pip install unfamiliar
```

---

## Tag Reference

| Tag pattern | Workflow | Publishes to |
|-------------|----------|--------------|
| `v0.1.0-rc1`, `v0.2.0-rc2` | `publish-test.yml` | TestPyPI |
| `v0.1.0`, `v0.2.0` | `publish.yml` | Production PyPI |

## One-Time Setup Required

Before first release, set up Trusted Publishers on both:

**TestPyPI:**
- test.pypi.org → Publishing → Add pending publisher
- Project: `unfamiliar`, Workflow: `publish-test.yml`, Environment: `testpypi`

**PyPI:**
- pypi.org → Publishing → Add pending publisher
- Project: `unfamiliar`, Workflow: `publish.yml`, Environment: `pypi`
