security-game/.agents/skills/gig-line-release-qa/references/release-runbook.md

Release Runbook

Authoritative source: AGENTS.md (Release Procedure), docs/process/RELEASING.md. This runbook is the operational checklist; if it conflicts with those, they win.

0. Decide the release

Determine whether this is a major, minor, patch, or release-candidate checkpoint. Do not assign a version to an unversioned development track until its scope is accepted into a release.

Check the current release constraints in TODO.md:

• external playtest evidence
• legal/AI-provider/storefront review
• macOS signing/notarization policy
• target hardware matrix
• any manual QA gaps

If a final release would ship with unresolved blockers, prepare an RC or stop; do not create a final tag.

1. Prepare the version

Files to update:

File	Change
project.godot	config/version="X.Y.Z"
CHANGELOG.md	dated ## [X.Y.Z] — YYYY-MM-DD entry
README.md	latest/current version and summary
PLAN.md / docs/project/architecture.md	current version reference
docs/project/development-status.md	shipped capability/release result
TODO.md / DONE.md	close/move milestone when complete
MEMORY.md	release state and gotchas

Then commit the preparation before building.

2. Run gates

Use qa-gates.md as the command matrix. The minimum release gate is:

• Godot suite
• Python tooling tests
• documentation gate
• asset audits/fit/proportions
• 24-NPC budget
• 14 smoke scripts
• screenshot compare
• optional screen/realism judge with recorded model/attempts
• clean build and artifact checks

Any skipped check must be written into MEMORY.md or TODO.md with a reason.

3. Build in a clean worktree

Why: Godot can pack ignored tmp/ captures and build/ outputs into the export. A dirty build can produce 1.6–3.1 GB artifacts instead of ~160–240 MB.

git worktree add --detach /tmp/gig-line-release HEAD
cd /tmp/gig-line-release
./tools/build_releases.sh

Expected local artifacts:

build/gig-line-linux-<version>.x86_64
build/gig-line-windows-<version>.exe
build/gig-line-macos-<version>.zip
build/gig-line-web-<version>.zip
build/gig-line-desktop-hq-<version>.zip

CI additionally produces the NSIS setup and AppImage, for seven release assets.

4. Preflight and checksum

PUBLISH_DRY_RUN=1 ./tools/publish_release.sh <version>
sha256sum -c build/SHA256SUMS-<version>.txt

publish_release.sh checks non-empty artifacts and local free space before any API call. It writes checksums under build/ and does not upload them by default.

Inspect packages:

unzip -l build/gig-line-web-<version>.zip | head -20
unzip -l build/gig-line-desktop-hq-<version>.zip | head -20
unzip -p build/gig-line-desktop-hq-<version>.zip override.cfg

Web must contain index.html, index.wasm, index.pck, and player docs. Desktop HQ must contain the Linux/Windows executables, override.cfg, README.txt, CREDITS.md, PRIVACY.md, accessibility.md and known-limitations.md.

5. Runtime launch smoke

./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

For Web, serve build/web and check HTTP 200 for index.html, index.wasm, index.pck and docs. Do not claim browser interaction from a curl check.

Remove the temporary worktree after checks:

git worktree remove --force /tmp/gig-line-release

6. Tag and CI

From the real repository, on the release commit:

git tag -a "v<version>" -m "Gig Line <version>"
git push origin main "v<version>"

The tag triggers .gitea/workflows/build.yml: checks, export, installer, AppImage, release publish. Verify the run and assets:

• check job success
• build job success
• seven assets present
• tag/version/artifact names equal
• download links respond

Do not reuse a published tag. If a fix is needed, bump patch and repeat.

7. Manual publish fallback

Only if CI cannot publish:

RETAIN_RELEASES=7 ./tools/publish_release.sh <version>

The script reuses or creates the release, uploads present artifacts, verifies the asset count, and rolls back newly uploaded assets/new release on failure. The default retention is 0 (no deletion). Never delete older releases implicitly.

8. Post-release record

Commit a release record that includes:

• tag and commit
• CI run/result
• seven assets
• checksums or size evidence
• skipped checks
• known limitations
• release URL

Update DONE.md/TODO.md and MEMORY.md; keep the changelog and README consistent. Push the record commit.

Versioning pitfalls

• A vX.Y.Z tag is immutable in practice; do not move/replace it.
• A release candidate is not a final release. Do not label it as such in the README or release page if blockers remain.
• config/version must match the tag and artifact filenames.
• The clean-worktree build is a release requirement, not an optimization.