172 lines
4.9 KiB
Markdown
172 lines
4.9 KiB
Markdown
# 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.
|