alexei.dolgolyov
0716d602e2
Some checks failed
Lint & Test / test (push) Failing after 13s
Create contexts/ci-cd.md documenting release pipeline, build scripts, CI runners, and versioning. Reference it from CLAUDE.md context table. Add mandatory pre-commit lint check rule to CLAUDE.md.
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# 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
|