--- name: gig-line-release-qa description: Use when preparing, validating, tagging or publishing a Gig Line release or release candidate, or when running the full screenshot, screen-design and realism QA gates. Covers version/changelog discipline, smoke and tooling matrices, clean-worktree builds, checksums, Web/HQ verification, publish rollback and post-release records. Do not use for ordinary asset edits or feature work. compatibility: Gig Line repository checkout with Godot 4.7.2 on PATH and Python 3 + Pillow. Release export needs installed Godot export templates; publishing needs Gitea credentials and is intentionally CI/tag-driven. metadata: project: Gig Line domain: release-qa version: "1.0.0" triggers: release, tag, version bump, changelog, build releases, publish, screenshots, screen design, realism judge, release candidate, deployment --- # Gig Line Release and Visual QA Use this skill for version bumps, release candidates, tags, artifact builds, publishing, and the full visual/QA gate. For a Blender/asset rebuild, use `gig-line-blender-asset-contract` first. ## Read first 1. `AGENTS.md` — release procedure and verification rules. 2. `TODO.md` — current milestone, blockers and release exit criteria. 3. `docs/process/RELEASING.md` — build/publish commands, artifact list, macOS policy. 4. `docs/process/release-qa.md` — manual QA matrix and balance protocol. 5. `docs/project/development-status.md`, `CHANGELOG.md`, `README.md` — current claims. 6. `MEMORY.md` — release gotchas, especially the clean-worktree rule. A release is not just a tag. It includes a version bump, changelog, clean build, artifact/checksum verification, CI publication, and post-release records. ## Hard rules - **Do not tag while the TODO still lists unresolved release blockers.** Check external playtest, legal/AI provenance, signing and target-hardware items. - **Never reuse a tag.** If a published version needs a fix, bump the patch and create a new tag. - **Build from a clean checkout or detached worktree.** A normal working tree can pack ignored `tmp/` and `build/` content into exports, inflating a ~160 MB package to 1.6–3.1 GB. - A tag push triggers CI checks/build/publish. Do not upload manually unless CI is unavailable and you have followed the same preflight. - Do not commit generated realism runs, raw captures, API keys, or build artifacts. - The vision judge is an optional development aid with external API cost, never a hard CI gate. - Keep `project.godot`, changelog, tag and release asset version equal. ## Release workflow ### 1. Scope and version Choose the semantic increment from `AGENTS.md`: - MAJOR: incompatible/removed behavior, save/config contract or core-pillar replacement. - MINOR: new user-facing feature/venue. - PATCH: fixes and polish. Update: 1. `project.godot` `config/version`. 2. `CHANGELOG.md` with a dated entry. 3. `README.md`, `PLAN.md`, `docs/project/architecture.md`, `docs/project/development-status.md`, `TODO.md`/`DONE.md` and `MEMORY.md` as needed. For a release candidate, use a prerelease version only if the project policy allows it and never present it as the final release. ### 2. Preflight ```bash git status --short git log --oneline -5 git tag -l "v" rg -n 'config/version' project.godot ``` Expected: only intended release changes; tag does not exist; version matches the changelog and planned artifacts. ### 3. Automated checks ```bash godot --headless --path . --script res://src/test/test_runner.gd python3 -m unittest discover -s tools/tests -t tools -p 'test_*.py' python3 tools/check_docs.py python3 tools/blender_assets.py audit python3 tools/blender_assets.py fit python3 tools/npc_proportions.py report python3 tools/npc_pipeline.py audit ``` Then run the smoke matrix, using isolated user-data directories for tutorial/campaign: ```bash for s in smoke_audio smoke_crowd smoke_emergency smoke_npc_budget \ smoke_plan_verbs smoke_scenario_content smoke_session_shell \ smoke_timeline smoke_ui_flows; do godot --headless --path . --script res://src/test/$s.gd || exit 1 done XDG_DATA_HOME=/tmp/gig-line-campaign godot --path . --fixed-fps 60 \ --script res://src/test/smoke_campaign.gd XDG_DATA_HOME=/tmp/gig-line-tutorial godot --path . --fixed-fps 60 \ --script res://src/test/smoke_tutorial.gd -- --tutorial godot --path . --script res://src/test/smoke_movement.gd godot --path . --script res://src/test/smoke_props.gd godot --path . --script res://src/test/smoke_focus_radial.gd ``` Use a fresh `$XDG_DATA_HOME` for campaign/tutorial and check the exit code, not just the log. ### 4. Visual and judge gates ```bash ./tools/check_screenshots.sh python3 tools/screen_designs.py compare python3 tools/screen_designs.py judge --model auto # optional, record model/verdicts ``` For realism/venue work: ```bash godot --path . --script res://src/test/capture_realism.gd \ -- --out=res://docs/screens/realism//after python3 tools/scene_concepts.py realism --run docs/screens/realism/ \ --judge --model ``` Requirements: - Gallery: 21 good / 0 bad; screen judge has no unexplained `diff`. - Realism runs stay under `docs/screens/realism/` (gitignored); only decisions and committed sheets/docs are tracked. - Record judge model, run count/attempts, spend if exposed, and verdicts. - Review every `review` verdict; turn layout regressions into fixes or documented known limitations. ### 5. Clean build Commit the release preparation first, then build the committed tree in a clean worktree: ```bash git worktree add --detach /tmp/gig-line-release HEAD cd /tmp/gig-line-release ./tools/build_releases.sh ``` Verify artifact names/sizes and checksums: ```bash ls -lh build/gig-line-** PUBLISH_DRY_RUN=1 ./tools/publish_release.sh sha256sum -c build/SHA256SUMS-.txt ``` Check package contents: ```bash unzip -l build/gig-line-web-.zip | head unzip -l build/gig-line-desktop-hq-.zip | head unzip -p build/gig-line-desktop-hq-.zip override.cfg ``` Check the runnable Linux and HQ packages: ```bash ./build/gig-line-linux-.x86_64 --headless --quit-after 60 unzip -q build/gig-line-desktop-hq-.zip -d /tmp/gig-line-hq /tmp/gig-line-hq/gig-line-linux-.x86_64 --headless --quit-after 60 ``` Check Web static serving with a local HTTP server and `curl` for `index.html`, `index.wasm`, `index.pck` and the player docs. Windows/macOS/AppImage/installer checks require the target matrix; if unavailable, record that explicitly. Remove the worktree after verification: ```bash git worktree remove --force /tmp/gig-line-release ``` ### 6. Tag and publish Only after every gate is green: ```bash git add -A git commit -m "Release " git tag -a "v" -m "Gig Line " git push origin main "v" ``` CI builds and publishes on the tag. Verify: - Tag commit equals the release commit. - CI checks/build job succeeded. - Release page has the expected 7 assets (Linux, Windows, macOS, NSIS setup, AppImage, Web, Desktop HQ). - Asset names and download links point at the released version. `tools/publish_release.sh` preflights artifact size/free space, writes SHA-256 checksums, rolls back newly uploaded assets/release on failure, and supports opt-in retention: ```bash RETAIN_RELEASES=7 ./tools/publish_release.sh ``` The default `RETAIN_RELEASES=0` never prunes. ### 7. Post-release record Update `README.md`, `docs/project/development-status.md`, `MEMORY.md`, `CHANGELOG.md`, `TODO.md`/`DONE.md` and the release page with the built/CI result. Commit the release record and push. Record any skipped check and the reason; never leave a tag with unreported missing verification. ## Known gotchas - **Dirty build inflation:** always use the clean worktree above. - **`Class ... hides a global script class`:** remove stray `.gd` backups in `tmp/`, delete `.godot`, re-import. - **Screenshot staging:** `capture_ui_states.gd` needs its settle frames and staged state; do not capture a paused frame or a stale modal. - **Judge keys:** OpenRouter calls need `.env`/`OPENROUTER_API_KEY`; never commit the key or generated review folders. - **Tag builds publish automatically:** do not run a second manual publish that duplicates assets; use the existing release if re-running. - **macOS is unsigned unless policy changes:** record quarantine instructions and do not claim notarization. - **Release blockers are real:** external playtest, legal/storefront approval, AI-provider rights and target-hardware checks cannot be replaced by green unit tests. ## Bundled references - [`references/release-runbook.md`](references/release-runbook.md) — version, build, tag, CI, publish and rollback sequence. - [`references/qa-gates.md`](references/qa-gates.md) — full command matrix, expected results and evidence to record. ## Completion checklist - [ ] Version/changelog/docs/tag match. - [ ] No unresolved release blockers for a final tag. - [ ] Godot, Python, smokes, asset and docs gates pass. - [ ] Gallery and optional judges reviewed with evidence. - [ ] Clean worktree build and checksums verified. - [ ] Linux/HQ/Web checks recorded; unavailable platforms noted. - [ ] Tag pushed; CI/publish succeeded; seven assets verified. - [ ] Release record and durable docs committed.