# Clew Engine Release Checklist

## Quick Overview

This checklist prepares you for automated releases via GitHub Actions.

| Secret | Purpose | Required For |
|--------|---------|--------------|
| `PYPI_API_TOKEN` | Publish to PyPI | `pipx install clew-engine` |
| `GITHUB_TOKEN` | Push Docker, create releases | Automatic (built-in) |

---

## 1. Secrets Management Strategy

### Recommendation: GitHub Secrets ✅

**Why GitHub Secrets?**
- Native integration with GitHub Actions
- Zero additional infrastructure
- Automatic injection into workflows
- Encrypted at rest

**Alternatives Considered:**
| Option | Pros | Cons |
|--------|------|------|
| GitHub Secrets | Free, native | Per-repo |
| HashiCorp Vault | Enterprise-grade | Overkill for this |
| AWS Secrets Manager | Great for AWS | Vendor lock-in |
| 1Password | Dev-friendly | Extra dependency |

---

## 2. Required Accounts

### PyPI (Python Package Index)

1. **Create Account**: [pypi.org/account/register](https://pypi.org/account/register/)
2. **Enable 2FA**: Required for API tokens
3. **Create API Token**:
   - Go to Account Settings → API tokens
   - Add new token → Scope: "Entire account" (or project-specific after first upload)
   - Copy the token (starts with `pypi-`)

### GitHub Container Registry (GHCR)

- **No setup needed!**
- Uses `GITHUB_TOKEN` automatically
- Images published to: `ghcr.io/matchdav/clew-engine`

---

## 3. GitHub Secrets Configuration

### Navigate to Settings

```
https://github.com/matchdav/clew-engine/settings/secrets/actions
```

### Add These Secrets

| Secret Name | Value | Notes |
|-------------|-------|-------|
| `PYPI_API_TOKEN` | `pypi-...` | From PyPI account |

### Automatic Secrets (No Setup)

| Secret | Provided By |
|--------|-------------|
| `GITHUB_TOKEN` | GitHub Actions (automatic) |

---

## 4. Repository Variables

For the Clew PR Analysis workflow, also set:

```
https://github.com/matchdav/clew-engine/settings/variables/actions
```

| Variable Name | Value | Purpose |
|---------------|-------|---------|
| `CLEW_API_URL` | `https://api.clewengine.dev` | PR analysis endpoint |

And in Secrets:

| Secret Name | Value | Purpose |
|-------------|-------|---------|
| `CLEW_API_KEY` | `sk_live_...` | PR analysis auth |

---

## 5. Pre-Release Verification

### Run Locally First
```bash
# Build package
pip install build
python -m build

# Test install from wheel
pip install dist/clew_engine-0.1.0-py3-none-any.whl
clew --help

# Test Docker build
docker build -t clew-test .
docker run --rm clew-test --help
```

### Verify Secrets Are Set
```bash
# Check via GitHub CLI
gh secret list --repo matchdav/clew-engine

# Expected output:
# PYPI_API_TOKEN  Updated 2024-...
# CLEW_API_KEY    Updated 2024-...
```

---

## 6. Release Process

### Step 1: Update Version
```bash
# Edit pyproject.toml
version = "0.1.0"

# Edit src/clew/__init__.py
__version__ = "0.1.0"
```

### Step 2: Commit & Tag
```bash
git add -A
git commit -m "chore: bump version to 0.1.0"
git tag v0.1.0
git push origin main --tags
```

### Step 3: Monitor Release
```
https://github.com/matchdav/clew-engine/actions
```

**Workflow does:**
1. ✅ Build PyInstaller binaries (4 platforms)
2. ✅ Publish to PyPI
3. ✅ Push Docker to ghcr.io
4. ✅ Create GitHub Release with binaries

---

## 7. Post-Release Verification

```bash
# Test PyPI install (may take 1-2 min to propagate)
pipx install clew-engine
clew --version

# Test Docker
docker pull ghcr.io/matchdav/clew-engine:v0.1.0
docker run --rm ghcr.io/matchdav/clew-engine:v0.1.0 --help

# Test install script
curl -fsSL https://raw.githubusercontent.com/matchdav/clew-engine/main/install.sh | bash
```

---

## 8. Checklist Summary

### One-Time Setup
- [ ] Create PyPI account and enable 2FA
- [ ] Generate PyPI API token
- [ ] Add `PYPI_API_TOKEN` to GitHub Secrets
- [ ] (Optional) Add `CLEW_API_URL` variable for PR analysis
- [ ] (Optional) Add `CLEW_API_KEY` secret for PR analysis

### Per-Release
- [ ] Update version in `pyproject.toml` and `__init__.py`
- [ ] Commit and create tag: `git tag v0.x.x`
- [ ] Push with tags: `git push --tags`
- [ ] Monitor GitHub Actions
- [ ] Verify installations work

---

## 9. Troubleshooting

### PyPI Upload Fails
- Check token has correct scope
- Ensure version doesn't already exist on PyPI
- Try `twine upload --verbose dist/*` locally

### Docker Push Fails
- GHCR uses `GITHUB_TOKEN` automatically
- Check repository visibility (public packages are free)

### Install Script Can't Find Binary
- Binaries only exist after first release
- Falls back to `pip install` automatically
