Skip to content

docs(skills): correct four claims the testbeds disproved - #3256

Merged
vpetersson merged 3 commits into
Screenly:masterfrom
vpetersson-bot:docs/testbed-runbook-corrections
Aug 5, 2026
Merged

docs(skills): correct four claims the testbeds disproved#3256
vpetersson merged 3 commits into
Screenly:masterfrom
vpetersson-bot:docs/testbed-runbook-corrections

Conversation

@vpetersson-bot

Copy link
Copy Markdown
Contributor

Issues Fixed

No associated issue. Corrections to the committed knowledge-base skills,
each one something the physical testbeds disproved during the 2026.08.0
release QA.

Description

Four claims in the runbooks were wrong or misleading. All four cost real
debugging time during the last QA round, so they are worth fixing at the
source rather than re-learning.

1. testbed-qa §4 — "linuxfb boards don't need force-display" is not
reliable.
The Pi 3 A+ runs QT_QPA_PLATFORM=linuxfb but boots
dtoverlay=vc4-kms-v3d, so headless it has no /dev/fb0 at all and the
viewer waits forever. It needs the same treatment as the eglfs boards.
Decide from the display driver, not the Qt platform name. Also documented:
the forced mode is a request, not a guarantee — two boards came up at
1024x768 despite asking for 1920x1080, which silently invalidates any
capture geometry computed from the config.

2. testbed-qa §4 — check for a pre-existing modifier and leave a
backup.
One board had carried a force-display cmdline for weeks with no
.bak-qa, which both made it unrepresentative of a headless device and
left later sessions nothing safe to restore. Its cmdline.txt.orig is
not a substitute — restoring it would change the console and drop
cgroup-memory flags.

3. testbed-qa §5 — two traps. pkill -f matches the pattern inside
its own SSH command line and kills the session running it (the runbook
warned about this for pgrep watchers only). And /tmp is a ~948 MB
tmpfs mounted usrquota with the quota shared across concurrent
sessions: exhausting it breaks the harness's own output capture, not just
the write. Multi-megapixel fixtures belong under the user's home.

4. testbed-qa §6 — the Rock Pi 4 claim was measured wrong. It said
the board "could not settle the latest viewer even with an empty
playlist". The playlist was not empty — four assets were enabled,
including a webpage and a streaming asset, left over from an earlier run.
Re-measured properly: the viewer alone fits comfortably; celery is
what drives swap to zero, and it does so on both the release build and
the previous baseline, so it is this board's steady state rather than any
build's regression. Added the standing instruction to verify the playlist
is genuinely disabled before quoting an idle memory number.

5. cut-release step 4 — a draft release does not create the tag.
GitHub defers tag creation until publish, so the tag is absent and the
URL is an untagged-<hash> placeholder until step 6. Worth stating
plainly because it makes the draft step risk-free: a blocker found during
QA costs you nothing to unwind. Also recorded that the board matrix is 7
boards (a preflight loop inventing pi1/pi4 reports false gaps) and
that the 32-bit pi3 legitimately has no rpi-imager .json.

Checklist

  • I have performed a self-review of my own code.
  • New and existing unit tests pass locally and on CI with my changes.
  • I have done an end-to-end test for Raspberry Pi devices.
  • I have tested my changes for x86 devices.
  • I added a documentation for the changes I have made (when necessary).

Documentation-only change to .claude/skills/; no code paths touched, so
the test and device boxes do not apply. Every correction here is itself
derived from measurements on the Pi 2 / Pi 3 A+ / Pi 3-64 / Pi 4 / Rock
Pi 4 testbeds.

- §4: a nominally-linuxfb board can still need force-display (Pi 3 A+
  runs vc4-kms and has no /dev/fb0 headless); forced modes may not
  take at the requested resolution
- §5: pkill -f matches its own ssh command line; /tmp is a quota'd
  tmpfs whose exhaustion breaks the harness, so no big fixtures there
- §6: on the Rock Pi 4 celery exhausts swap, not the viewer — the
  original claim was measured with assets still enabled
- cut-release: a draft release does not create the tag
@vpetersson-bot vpetersson-bot self-assigned this Aug 5, 2026
@vpetersson-bot
vpetersson-bot requested a review from a team as a code owner August 5, 2026 17:05
- §3: build the overlay from the commit object, not the shared working
  tree, which gets switched under you mid-run; and note the pinned
  image may predate your branch base
- §5: viewer idle RSS varies hugely between restarts, so A/B inside one
  lifetime; memory.peak is fd-local and a reset-then-read lies
- §5: never tick a PR device box from intent, only with numbers
- bak-predeploy-<hash> was read both ways, so both conventions now
  exist on the fleet with opposite meanings
- on the Pi 4 and Rock Pi 4, bak-predeploy-fbe83e9 pins latest-<board>
  while bak-predeploy-fbe83e9-qa2 really pins fbe83e9
- name new backups after their contents, and grep before any restore
@sonarqubecloud

sonarqubecloud Bot commented Aug 5, 2026

Copy link
Copy Markdown

@vpetersson
vpetersson merged commit bcc994e into Screenly:master Aug 5, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants