DX: replace binary golden .ppm fixtures with a text-diffable baseline #30

New issue

Closed

opened 2026-08-30 12:50:27 +02:00 by orkun · 1 comment

orkun commented

2026-08-30 12:50:27 +02:00

Owner

Problem

selfhost/golden/ holds 4 binary .ppm golden files (chronorift.ppm,
draw_prims.ppm, menu.ppm, snake.ppm) used as render-output baselines. This is
poor DX:

Binary blobs in git — every regen bloats history and produces opaque diffs
("Binary files differ"), so a reviewer can't tell what actually changed.
Regenerating them is a manual, trust-me step; it's easy to bless a wrong image.
PPM specifically is large and uncompressed.

Proposal

Pick a verification strategy with a legible signal instead of committed binaries:

Hash-based golden: store a checksum (or small manifest of per-frame hashes)
of the rendered framebuffer and compare in bin/x test. Tiny, text-diffable,
no image blobs.
If a visual reference is genuinely needed, keep it out of the source history
(generated artifact, or committed as PNG with an explicit "regenerate with
bin/x …" doc), and diff structurally, not byte-for-byte.
Whatever the choice, add a documented one-command way to regenerate and
review a baseline so blessing an update is deliberate.

Acceptance criteria

No opaque binary golden blobs committed as the primary baseline.
Render regressions are caught by a text-diffable signal (hashes/manifest).
Documented, single-command regenerate + review flow.

Part of the repository-cleanup / DX pass.

## Problem `selfhost/golden/` holds **4 binary `.ppm` golden files** (`chronorift.ppm`, `draw_prims.ppm`, `menu.ppm`, `snake.ppm`) used as render-output baselines. This is poor DX: - Binary blobs in git — every regen bloats history and produces **opaque diffs** ("Binary files differ"), so a reviewer can't tell what actually changed. - Regenerating them is a manual, trust-me step; it's easy to bless a wrong image. - PPM specifically is large and uncompressed. ## Proposal Pick a verification strategy with a legible signal instead of committed binaries: - **Hash-based golden**: store a checksum (or small manifest of per-frame hashes) of the rendered framebuffer and compare in `bin/x test`. Tiny, text-diffable, no image blobs. - If a visual reference is genuinely needed, keep it out of the source history (generated artifact, or committed as PNG with an explicit "regenerate with `bin/x …`" doc), and diff structurally, not byte-for-byte. - Whatever the choice, add a documented one-command way to **regenerate and review** a baseline so blessing an update is deliberate. ## Acceptance criteria - [ ] No opaque binary golden blobs committed as the primary baseline. - [ ] Render regressions are caught by a text-diffable signal (hashes/manifest). - [ ] Documented, single-command regenerate + review flow. Part of the repository-cleanup / DX pass.

orkun added the

priority:low

area:tooling

cleanup

labels 2026-08-30 12:50:27 +02:00

orkun referenced this issue from a commit

2026-08-30 17:57:48 +02:00

chore(repo): DX cleanup — categorise examples, text-diffable golden, build/ output (#27 #28 #30)

orkun commented

2026-08-30 18:01:41 +02:00

Author

Owner

Done in fb728bb.

The 4 binary selfhost/golden/*.ppm fixtures are gone, replaced by a single text baseline: selfhost/golden/renders.sha256 — one <path> <sha256> line per render.

Acceptance criteria

No opaque binary golden blobs — the .ppm files are deleted; the primary baseline is now hashes in a text file.
Text-diffable regression signal — game_case renders each game headless and compares the framebuffer's SHA-256 against the manifest. A regression is a changed hex line in review, not "binary files differ".
Documented single-command regenerate + review flow — new bin/x golden re-renders the four goldens and rewrites the manifest, printing review the change: git diff selfhost/golden/renders.sha256. Render keys live in one place, shared by the checks and the regenerator so they can't drift.

The new hashes are byte-identical to the retired PPMs (verified before deleting them), so this changes the baseline's form, not its content.

Done in fb728bb. The 4 binary `selfhost/golden/*.ppm` fixtures are gone, replaced by a single text baseline: `selfhost/golden/renders.sha256` — one `<path> <sha256>` line per render. **Acceptance criteria** - [x] **No opaque binary golden blobs** — the `.ppm` files are deleted; the primary baseline is now hashes in a text file. - [x] **Text-diffable regression signal** — `game_case` renders each game headless and compares the framebuffer's SHA-256 against the manifest. A regression is a changed hex line in review, not "binary files differ". - [x] **Documented single-command regenerate + review flow** — new `bin/x golden` re-renders the four goldens and rewrites the manifest, printing `review the change: git diff selfhost/golden/renders.sha256`. Render keys live in one place, shared by the checks and the regenerator so they can't drift. The new hashes are byte-identical to the retired PPMs (verified before deleting them), so this changes the baseline's form, not its content.

orkun closed this issue

2026-08-30 18:01:47 +02:00

orkun referenced this issue

2026-08-30 18:08:11 +02:00

Repo cleanup: fix PPM & asset handling (out.ppm, golden blobs, duplicated Kenney art) #27