diff --git a/docs/review/LESSONS.md b/docs/review/LESSONS.md index dd576e70c..96de25c09 100644 --- a/docs/review/LESSONS.md +++ b/docs/review/LESSONS.md @@ -483,6 +483,11 @@ never change, so reviews can cite them. that isn't cheetah; name a log line or a compositor query instead. Extends L-295 and L-276. *From:* kernel #212, round 44 (a near miss in drafting); 2026-11-08. + Again in round 45, the right way round: kernel #212's author counted the + DECON frame-start interrupt in `/proc/interrupts` under a redrawing terminal + (120/60/121 per second), read-only and device-neutral; name that (`grep -i + decon /proc/interrupts` twice, a second apart) when asking another phone for + a rate. - **L-533. A lens or OIS controller at the same I2C address as the module's calibration EEPROM is a calibration part.** Stock's tegu DT puts `eeprom-nessie`, `act-nessie` and `ois-nessie` all at 0x24: the LC898129 @@ -491,6 +496,33 @@ never change, so reviews can cite them. writes only the registers it names, and the notes list every register written during bring-up. Extends L-90 and L-108. *From:* kernel #213, round 44, 2026-11-08. +- **L-562. A custom recovery or installer in a contributor's record is a slot + question first.** Kodiak's notes said a step was "taken from" a third-party + recovery and sat merged through two rounds; the answer, "installed to + `vendor_boot` on both slots, may have mounted persist", means slot A was + written, the fallback recovery is no longer stock's, and the calibration + backup and slot B's rollback set may not be stock's either. *Check:* + whenever a third-party recovery, root tool or installer appears, ask which + partitions on which slots it wrote (`vbmeta` flags included), when relative + to each backup, and what it mounted; record a slot A write as a §3.1 event + and downgrade any backup taken under it (L-198). Extends L-186, L-198 and + L-35. *From:* #511 with #489 and #231, round 45, 2026-11-08. +- **L-563. A locally administered MAC that a PR makes persistent is an + identifier, and `tools/pr-check` exempts it and reads no commit message or + PR body.** #510 saves a random address pair per phone, so the contributor's + example in the body and commit now names their phone to every host it meets. + *Check:* for a PR that stores generated addresses or IDs, grep the body, + every commit message and the thread for them (the L-324 pattern without the + locally-administered exemption), and ask for placeholders and a rotation. + Extends L-324 and L-145. *From:* #510, round 45, 2026-11-08. +- **L-564. `reboot-to` (and `bin/omamobile push`) stops no unit, so with the + modem up it leaves `/var/lib/omamobile/modem-up` behind and the next boot + skips the modem once.** *Check:* a runbook or test plan that reboots a phone + with the modem up stops it first (`systemctl stop omamobile-modem`; it takes + about 40 s and ends as "failed" for now, issue #532), or uses `systemctl + reboot`. To keep the modem off for a boot it is `systemctl mask + omamobile-modem-boot.target`, not `/etc/omamobile/modem-hold`, which matters + only after an unclean end. *From:* the 2026-11-08 7 Pro session, issue #532. ## Shared code and the reference device @@ -903,6 +935,58 @@ never change, so reviews can cite them. data's `model`. *Check:* the driver's `v4l2_i2c_subdev_set_name` argument, the match table, and `git grep` of the compatible in the gs201 DTs. Extends L-206. *From:* #494, round 44, 2026-11-08. +- **L-565. An error-path-only fix in a shared driver is cheetah-neutral in + behaviour only while that error never happens, and its object still + changes.** Kernel #222's one `break` reallocated registers across + `s3c64xx_spi_transfer_one` (and moved the readl pool into `runtime_resume`'s + last line), and the 7 Pro has three SPI users that chunk in PIO. *Check:* + grep `logs/` for the error line the new branch follows (`I/O Error: rx-`: 0 + in 1000 logs) before calling the change invisible, and let the 7 Pro run + record "not exercised" with that count rather than "the fix works". Extends + L-51, L-206 and L-440. *From:* kernel #222, round 45, 2026-11-08. +- **L-566. A doc change we ask for in a shared package's plan is checked for + which phone it claims.** On #376 we asked that the 7 Pro's MODEM-PLAN stop + saying "a second start isn't supported" once the code changed; the reworded + line states the new behaviour as a 7 Pro fact, measured only on the 9a. + *Check:* for each sentence a PR changes under `device//`, find the run on + that device that supports it, or ask for "on the ; not yet run + here". Extends L-188 and L-31. *From:* #376, round 45, 2026-11-08. +- **L-567. A public device package tested next to a private companion is + checked for which safety nets live only in the companion.** #222's oriole + package installed cleanly, but only alongside a private package carrying the + reboot watchdog and a boot check, and `device.conf`'s `PACKAGE=` makes the + public one alone the image's device package. *Check:* when a smoke report's + package list names a `*-local-*` or private package, ask what it ships, and + map each safety file to the public package or to a "not supported yet" line + in the README. Extends L-61, L-158 and L-358. *From:* #222, round 45, + 2026-11-08. +- **L-568. L-8 runs without touching anyone's build directory.** Copy a kernel + output's `arch/arm64/boot/Image`, the device's DTBs, + `scripts/dtc/{dtc,fdtoverlay}`, `initramfs.cpio.lz4` and + `include/config/kernel.release` (and `initramfs.release`) into a scratch + `KERNEL_OUT`, then run `DEVICE=cheetah images` with main's `bin/omamobile` + (`git show origin/main:bin/omamobile`) and the PR's from the same worktree. + `images` writes only `$KERNEL_OUT/images`, and a stale build is fine for a + before/after compare. *Check:* six equal sha256s. Extends L-8 and L-194. + *From:* #507, round 45, 2026-11-08. +- **L-569. A fix that updates every `cmp`-pinned copy of a shared source goes + stale when a new package with the same pin merges first, and then it turns + main red.** #459 updated seven `reboot-to.c` copies; akita's package, with + the same `cmp` against cheetah's file, merged two days later (#456), so #459 + as it stands fails akita's `test/all` and needs an akita version that #509 + is about to take. *Check:* each round, for every open PR that edits a file + other packages pin, `git grep -l '' origin/main -- + 'packages/*/test/all'` against the PR's file list, and put the missing + packages and their next free versions in the merge plan. Extends L-257 and + L-426. *From:* #459 with #456 and #509, round 45, 2026-11-08. +- **L-570. A test kernel for `bin/omamobile push` needs four steps into its + `KERNEL_OUT`: `kernel`, `initramfs`, `images` (with `DEVICE=cheetah`) and + `modules`.** `push` refuses before any write when one is missing ("holds + images for … an unknown device", "build the initramfs first", the missing + modules tarball), so a skipped step costs a round trip, not the phone. + *Check:* a runbook that hands the human a test kernel lists all four with + the same `KERNEL_DIR`/`KERNEL_OUT`, in that order. *From:* the 2026-11-08 7 + Pro session. ## Shell and scripts @@ -1004,6 +1088,11 @@ never change, so reviews can cite them. Again in round 44: a "some `c N:*` line exists" pattern on #493 matched unrelated wildcard lines (`c 5:*`, `c 136:*`); found by deleting the line under test. + Again in round 45: #501's "reaches the MANIFEST" case read what its stub + `docker` printed, so it proved the plumbing and not the producer, and #505's + `tests/dipper-probe` checked that its needles are in `initramfs-inside.sh`, + always true, instead of feeding the real `initramfs/init` through the patch + step. - **L-467. `RestartPreventExitStatus=` covers the main process only; a pre-start refusal that must not be retried uses `ExecCondition=`.** #371's `ExecStartPre=` check exited 3 with `RestartPreventExitStatus=3`; on @@ -1146,6 +1235,53 @@ never change, so reviews can cite them. at or above 234 and outside `Documentation/admin-guide/devices.txt`'s fixed list gets a path-based rule, a value generated at start, or an update plan. *From:* #493, round 44, 2026-11-08. +- **L-571. An allow line added because "Waydroid binds it" is checked for what + the node lets the container do to the host.** #493's `/dev/uhid` creates HID + devices that the host compositor reads, which is a way to inject input into + the host session; Android booted without it and logged nothing about it. + *Check:* for each new `lxc.cgroup2.devices.allow`, name the host object that + opening the node creates or reaches (uhid and uinput are host input, `kvm` + host CPU state, `mem` and `port` host memory and I/O), and ask for a failing + Android feature without it before it goes in. Extends L-540 and L-454. + *From:* #493, round 45, 2026-11-08. +- **L-572. A lock added to an input handler is checked for what a holder that + hangs does to every later press.** #508's `flock` without `-w` made a stuck + short-press action freeze the power key for the session, where main would + have let the next press through. *Check:* for any new `flock`, mutex or + queue in a key, touch or wake path, run the PR's harness with the slowest + helper made to sleep past the press interval, measure when the next press + acts on main and on the head, and ask for a bound. Extends L-161 (fail + towards the user being able to act). *From:* #508, round 45, 2026-11-08. +- **L-573. Deferring a surface's "on open" reads is checked against what the + surface shows first and what refreshes it while it's closed.** #518 queued + the shade's notification read ninth, behind the reveal, and the shade's + periodic read runs only while it's open (`running: root.opened`, first tick + at 3 s), so every open showed the previous open's list for about 0.65 s. + *Check:* for each read moved off the open path, `grep -n` its function for + the timers and watchers that call it, note their `running:` condition, and + compute when the first fresh value appears after opening; ask that what the + first screen shows goes first. Extends L-235. *From:* #518, round 45, + 2026-11-08. +- **L-574. (Provisional, not yet checked on a phone.) A network-sharing + feature is checked against the firewall the image turns on.** #525 makes the + hotspot's dnsmasq start, but firstboot's ufw denies incoming and forwarded + traffic, so a client's DHCP and DNS may never reach it, and the PR's test + (the server side came up) can't show that. *Check:* `git grep -n 'ufw ' + packages/omamobile-firstboot` for the defaults, and ask for one client test + (an address, then a ping out) before a "hotspot works" claim. Confirm or + drop once a client test has run. *From:* #525, round 45, 2026-11-08. +- **L-575. A Mesa `pkgrel` bump moves `_omamobile` with it (1.3 with + omamobile3, 1.4 with omamobile4).** The marker is what shows in `GL_VERSION` + and the libgallium name, so a bump that leaves it reports the old build on + the phone. *Check:* `git log -p -- packages/mesa/PKGBUILD | grep -E + '^[-+](pkgrel|_omamobile)='` on every Mesa PR. *From:* #500, round 45 + (missed in round 44), 2026-11-08. +- **L-576. A build host that is not Arch runs the tools' pacman steps in the + container, with that container's view of keys and users.** `repo-add` there + ran as `-u $(id -u)`, which under rootless Docker can't read the release + keyring (#544), and the Omarchy keyring isn't on the host at all (#547). + *Check:* a dry run of `tools/repo-publish` on a new build host before its + publish timer is enabled. *From:* #544, #547, 2026-11-08. ## Kernel (linux-omarchy-mobile) @@ -1770,6 +1906,77 @@ never change, so reviews can cite them. diff ` with `git diff `, and grep the difference for any reference-phone path. Extends L-45, L-122 and L-195. *From:* kernel #187, round 44, 2026-11-08. + Again in round 45: for kernel #187, `git diff --stat` listed only zuma, husky and akita files, and a per-function + object compare of the prebuilt base/test pair (same-source control objects + first, at 0 changes) answered "what changes on cheetah" without a rebuild; + give the contributor the expected tree id of the rebase. +- **L-577. A draft whose commits a sibling stack carries is checked by + patch-id per commit, and closed with a note to its author, not merged.** 22 + of kernel #156's 25 remaining commits are patch-identical in #187 and the + other 3 differ in context only; saying so, with ids, answers "is anything + lost if we close it", and a request made on the draft (gate the split) is + retired where the sibling's thread settled it. *Check:* `git cherry` against + the base, then `git patch-id --stable` on both lists, and grep the sibling + thread for each open request. Extends L-182 and L-429. *From:* kernel #156 + with #187, round 45, 2026-11-08. +- **L-578. A blob check that fails on one file is narrowed to the nodes the + test used before we ask for another boot.** Kernel #209's tested + `zuma-husky.dts` differed from the head only by other test nodes around it; + the `nfc@8` node, its pin groups, the PMU's `#clock-cells`, + `clk-exynos-clkout.c` and `nxp-nci/i2c.c` were identical. *Check:* for each + differing file, extract the nodes or functions the test exercised (`sed -n + '/