From a8cf9ef337742bb6d0cb7d9a2957bea91aeebf49 Mon Sep 17 00:00:00 2001 From: ekklesia Date: Fri, 4 Sep 2026 17:07:30 -0500 Subject: [PATCH] docs: record the classroom test checklist and DVD notes The checklist covers the bottom-shell regression explicitly, since that is the part most likely to be broken by a later change, and records the known limitation that Chrome's own minimize button does nothing under sway. Co-Authored-By: Claude Opus 5 --- docs/dvd.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++ docs/testing.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 docs/dvd.md create mode 100644 docs/testing.md diff --git a/docs/dvd.md b/docs/dvd.md new file mode 100644 index 0000000..737f38d --- /dev/null +++ b/docs/dvd.md @@ -0,0 +1,82 @@ +# DVD support + +DVD support is optional per classroom and off by default. + +## Enabling a room + +Edit `/etc/ekklesia-classroom/device.conf` on that endpoint: + +``` +DVD_ENABLED=true +``` + +Then restart the session (reboot, or restart `classroom-dock`). + +With `DVD_ENABLED=false`, or the key absent, the DVD button is not built +at all and no drive polling happens. Older endpoints get a commented +`DVD_ENABLED=false` appended on upgrade so the option is discoverable, +which leaves their behaviour unchanged. + +## Behaviour + +The dock polls the drive every two seconds with the `CDROM_DRIVE_STATUS` +ioctl. That is a status query, so it does not spin the disc up. + +| State | Dock icon | Clicking the button | +| --- | --- | --- | +| No drive connected | DVD logo held back at 55% | "No DVD drive is connected to this classroom computer." | +| Drive present, no disc | DVD logo held back at 55% | "No disc is in the drive. Insert a disc to get started." | +| Tray open | held back | "The disc tray is open. Insert a disc to get started." | +| Disc still being read | held back | "Reading the disc. Please try again in a moment." | +| Disc ready | DVD logo at full strength | Plays the disc | + +When a disc becomes ready, a **DVD Ready** notification is shown once. +Discs never play on their own; playback always needs a button press. + +The first poll after login only records what is already in the drive, so +a disc left in over the week does not announce itself at every boot. + +## Playback + +Playback is VLC, chosen over mpv because mpv dropped DVD menu support. +VLC's `dvdnav` path gives working menus, chapters and audio tracks. + +`classroom-dvd toggle` hands the disc to VLC through `classroom-window`, +so the DVD player behaves like any other classroom application: the DVD +button focuses it, minimises it, and restores it. `Super+M` minimises it +too. VLC starts fullscreen; `Esc` leaves fullscreen. + +## Commercial (CSS encrypted) discs + +Most retail DVDs are CSS encrypted, and Debian cannot ship the +decryption library. Unencrypted discs — curriculum discs, home-burned +video — play without any extra work. + +For commercial discs, run once per endpoint, as root: + +``` +sudo classroom-dvd-css-setup +``` + +That enables the Debian `contrib` component, installs `libdvd-pkg` and +builds `libdvdcss`. It needs network access and it compiles a package, +which is why it is deliberately not run from the package `postinst`: the +postinst runs while dpkg already holds the apt lock during an OTA update. + +**Commercial DVD playback has not been verified on hardware yet.** Test +with an actual disc before relying on it for a service. + +## Command line + +``` +classroom-dvd status # drive node, drive state, whether VLC is installed +classroom-dvd toggle # what the dock button does +classroom-dvd play # start playback even if the drive is unsure +classroom-dvd eject # open the tray +``` + +## Permissions + +Reading the drive needs group `cdrom`. The postinst adds the `classroom` +user to it; that takes effect at the next login, which the OTA reboot +provides. Without it the drive reads as absent. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..29bf1d4 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,87 @@ +# Classroom test checklist + +Run against the exact artifact published to canary, on the real endpoint, +before promoting to stable with `./update_stable.sh`. + +## Boot + +- [ ] Cold boot reaches the classroom shell with no terminal or window junk +- [ ] Reboot does the same +- [ ] Wallpaper appears +- [ ] Dock appears, centred +- [ ] Clock appears, bottom right + +## Reserved bottom shell (regression) + +The bottom strip is one full-width layer-shell surface with a 76px +exclusive zone. Dock and clock live inside it. Do not split them back +into separate layer-shell windows. + +- [ ] A maximised Chrome window stops above the bottom strip +- [ ] The clock does not float over Chrome +- [ ] Dock stays centred, clock stays bottom right +- [ ] Wallpaper shows through the unused parts of the strip +- [ ] Every dock button still responds to clicks +- [ ] A fullscreen application covers the whole display, dock included + +## Browser + +- [ ] First Browser click launches Chrome +- [ ] Chrome opens on Wonder Ink (https://app.wonderink.org/) +- [ ] Clicking Browser while Chrome is focused minimises it +- [ ] Clicking Browser again restores it **maximised, not floating or draggable** +- [ ] Clicking Browser while Chrome is running but unfocused focuses it +- [ ] `Super+M` minimises the focused window +- [ ] `Super+Shift+M` restores the most recently minimised window +- [ ] Normal navigation to any other site works +- [ ] The Home button returns to Wonder Ink +- [ ] Fullscreen YouTube video uses the whole display +- [ ] Leaving fullscreen restores the correct geometry above the dock +- [ ] No first-run, default-browser or sign-in nag appears +- [ ] Chrome does not start by itself at boot +- [ ] After a reboot, cookies and site logins are still there +- [ ] After an OTA update, cookies and site logins are still there + +Known limitation: Chrome's own minimise button in its title bar does +nothing. Sway ignores the Wayland minimise request and gives no event to +hook. Minimising is the dock's Browser button or `Super+M`. + +## Notifications + +- [ ] `classroom-notify-test` renders with the classroom styling: + dark translucent, rounded, white text, top right +- [ ] `classroom-notify-test --critical "Parent Call" "Room 3 needs a parent."` + renders in the critical style and does not time out +- [ ] Notifications appear over a fullscreen video + +## DVD + +With `DVD_ENABLED=false`: + +- [ ] No DVD button in the dock + +With `DVD_ENABLED=true`: + +- [ ] Drive unplugged: button present, icon held back, friendly notification on click +- [ ] Drive present, no disc: friendly notification on click, nothing crashes +- [ ] Inserting a disc produces one **DVD Ready** notification +- [ ] The DVD icon comes up to full strength while a disc is in +- [ ] Nothing plays until the button is pressed +- [ ] Clicking plays the disc +- [ ] Menus work +- [ ] Audio works +- [ ] Chapter navigation works +- [ ] Fullscreen works +- [ ] `Super+M` minimises the player, the DVD button restores it +- [ ] Closing the player works +- [ ] Ejecting is detected, the icon goes back +- [ ] Reinserting is detected again +- [ ] Commercial CSS disc, after `classroom-dvd-css-setup` + +## OTA + +- [ ] `./update_canary.sh` publishes package first, manifest last +- [ ] The endpoint on the canary channel picks the update up +- [ ] SHA-256 verification passes +- [ ] Install succeeds and the endpoint reboots +- [ ] Everything above still works after the update