Add tracked AI skills for Blender assets and release QA
This commit is contained in:
zwitschi committed
1 parent
e4e1566e55
commit
724e8b183f
13 files changed
+1124
-25
No files matched your search
@@ -0,0 +1,254 @@
|
||||
---
|
||||
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/RELEASING.md` — build/publish commands, artifact list, macOS policy.
|
||||
4. `docs/smoke-checklist.md` — manual QA matrix.
|
||||
5. `docs/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/architecture.md`,
|
||||
`docs/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<version>"
|
||||
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/<run>/after
|
||||
python3 tools/scene_concepts.py realism --run docs/screens/realism/<run> \
|
||||
--judge --model <pinned-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-*<version>*
|
||||
PUBLISH_DRY_RUN=1 ./tools/publish_release.sh <version>
|
||||
sha256sum -c build/SHA256SUMS-<version>.txt
|
||||
```
|
||||
|
||||
Check package contents:
|
||||
|
||||
```bash
|
||||
unzip -l build/gig-line-web-<version>.zip | head
|
||||
unzip -l build/gig-line-desktop-hq-<version>.zip | head
|
||||
unzip -p build/gig-line-desktop-hq-<version>.zip override.cfg
|
||||
```
|
||||
|
||||
Check the runnable Linux and HQ packages:
|
||||
|
||||
```bash
|
||||
./build/gig-line-linux-<version>.x86_64 --headless --quit-after 60
|
||||
unzip -q build/gig-line-desktop-hq-<version>.zip -d /tmp/gig-line-hq
|
||||
/tmp/gig-line-hq/gig-line-linux-<version>.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 <version> <topic>"
|
||||
git tag -a "v<version>" -m "Gig Line <version>"
|
||||
git push origin main "v<version>"
|
||||
```
|
||||
|
||||
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 <version>
|
||||
```
|
||||
|
||||
The default `RETAIN_RELEASES=0` never prunes.
|
||||
|
||||
### 7. Post-release record
|
||||
|
||||
Update `README.md`, `docs/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.
|
||||
Reference in new issue
Block a user