# CI/CD & Release Workflow

## Workflows

| File | Trigger | Purpose |
|------|---------|---------|
| `.gitea/workflows/test.yml` | Push/PR to master | Lint (ruff) + pytest |
| `.gitea/workflows/release.yml` | Tag `v*` | Build artifacts + create Gitea release |

## Release Pipeline (`release.yml`)

Four parallel jobs triggered by pushing a `v*` tag:

### 1. `create-release`
Creates the Gitea release with a description table listing all artifacts. **The description must stay in sync with actual build outputs** — if you add/remove/rename an artifact, update the body template here.

### 2. `build-windows` (cross-built from Linux)
- Runs `build-dist-windows.sh` on Ubuntu with NSIS + msitools
- Downloads Windows embedded Python 3.11 + pip wheels cross-platform
- Bundles tkinter from Python MSI via msiextract
- Builds frontend (`npm run build`)
- Pre-compiles Python bytecode (`compileall`)
- Produces: **`LedGrab-{tag}-win-x64.zip`** (portable) and **`LedGrab-{tag}-setup.exe`** (NSIS installer)

### 3. `build-linux`
- Runs `build-dist.sh` on Ubuntu
- Creates a venv, installs deps, builds frontend
- Produces: **`LedGrab-{tag}-linux-x64.tar.gz`**

### 4. `build-docker`
- Plain `docker build` + `docker push` (no Buildx — TrueNAS runners lack nested networking)
- Registry: `{gitea_host}/{repo}:{tag}`
- Tags: `v0.x.x`, `0.x.x`, and `latest` (stable only, not alpha/beta/rc)

## Build Scripts

| Script | Platform | Output |
|--------|----------|--------|
| `build-dist-windows.sh` | Linux → Windows cross-build | ZIP + NSIS installer |
| `build-dist.sh` | Linux native | tarball |
| `server/Dockerfile` | Docker | Container image |

## Release Versioning

- Tags: `v{major}.{minor}.{patch}` for stable, `v{major}.{minor}.{patch}-alpha.{n}` for pre-release
- Pre-release tags set `prerelease: true` on the Gitea release
- Docker `latest` tag only applied to stable releases
- Version in `server/pyproject.toml` should match the tag (without `v` prefix)

## CI Runners

- Two TrueNAS Gitea runners with `ubuntu` tags
- No Windows runner available — Windows builds are cross-compiled from Linux
- Docker Buildx not available (networking limitations) — use plain `docker build`

## Test Pipeline (`test.yml`)

- Installs `opencv-python-headless` and `libportaudio2` for CI compatibility
- Display-dependent tests are skipped via `@requires_display` marker
- Uses `python` not `python3` (Git Bash on Windows resolves `python3` to MS Store stub)

## Common Tasks

### Creating a release
```bash
git tag v0.2.0
git push origin v0.2.0
```

### Creating a pre-release
```bash
git tag v0.2.0-alpha.1
git push origin v0.2.0-alpha.1
```

### Adding a new build artifact
1. Update the build script to produce the new file
2. Add upload step in the relevant `build-*` job
3. **Update the release description** in `create-release` job body template
4. Test with a pre-release tag first