# Release Runbook

Authoritative source: `AGENTS.md` (Release Procedure), `docs/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/architecture.md` | current version reference |
| `docs/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.

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

Expected local artifacts:

```text
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

```bash
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:

```bash
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

```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
```

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:

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

## 6. Tag and CI

From the real repository, on the release commit:

```bash
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:

```bash
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.