From ea680e4723ba07fbc2c88fc0aa3d8d1d00f1aca7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20M=C3=A9ndez?= Date: Mon, 28 Sep 2026 05:36:35 +0000 Subject: [PATCH 1/2] docs: the trap of reading product.mk from the wrong tkldev Two machines in this project answer to the hostname tkldev, the LXC container on a workstation and the build host, and they run different fab. Reading share/product.mk on the nearer one answers a question about the other, and the answer is internally coherent, cites a real file and survives a review, because the facts the work rests on are checked and correct while the sentence around them is not. It cost two review rounds on keel-core#9 on 2026-09-28: the build order was read from the container, which puts the common removelists before a single combined unit phase, while the build host has three unit phases before them. The correction then named fab 1.1.1+keel1, the one release that does not carry the order being described, so the note was wrong a second time in the same way. The entry records the three files with their md5 sums, so the fix is not an instruction to be careful but a check that takes one line: read it on the machine that builds, quote the md5 of the file you read, and say which fab version that is. Closes #12. --- docs/traps.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/traps.md b/docs/traps.md index 6d957a5..24fb6cd 100644 --- a/docs/traps.md +++ b/docs/traps.md @@ -326,6 +326,39 @@ today, which is what makes this easy to miss and easy to dismiss. **Hit** 2026-09-27, the LAMP composition measurement: 199 and 183 differing files, which are 198 and 182. +## Two machines answer to `tkldev`, and they run different fab + +**Signature.** A claim about the build order, or about anything else in +`product.mk`, that is internally coherent, cites a real file at a real path, +survives a review, and does not describe what the build does. Nothing in the +change depends on the wrong part, which is why it survives: the facts the work +rests on are checked and correct, and the sentence around them is not. + +**Cause.** The LXC container on a workstation and the build host both answer to +`tkldev`, and they run different fab. Reading `/usr/share/fab/product.mk` on +the nearer one answers a question about the other. Measured 2026-09-28: + +| Machine | fab | `product.mk` md5 | Unit phases in `root.patched/body` | +| --- | --- | --- | --- | +| local `tkldev` container | `1.1.1`, stock | `0657df1a` | one, after the common removelists | +| fab `1.1.1+keel1` (b07a733) | `1.1.1+keel1` | `c04cb601` | none | +| build host | `1.1.1+keel2` | `a06bfe03` | three (overlays, conf scripts, removelists), before the common removelists | + +**Fix.** Take the reading from the machine that builds, and name the fab +version beside it so the next reader can tell which file was read. A version +string alone is not enough: the first correction named `1.1.1+keel1`, the one +release that does not carry the order it was describing, and was wrong again in +the same way. Quote the md5 of the file the reading came from; `md5sum +/usr/share/fab/product.mk` on the build host settles it in one line, and +`dpkg-query -W fab` says which version that is. + +**Hit** 2026-09-28 in the core login change (keel-core#9). The order written +into `conf.d/main`, `COVERAGE.md` and the commit message put the common +removelists before the units, read faithfully from the container's file. The +two facts the change rested on were true in both versions, so the first review +passed it; the second caught it, and then caught the version string in the +correction. + ## Things we did wrong and would do again unless written down - **Discarding a local commit on a guess.** A checkout on the build host had a From 92fb316d46dc7ae4172cec55ab692c760c09c21c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20M=C3=A9ndez?= Date: Tue, 29 Sep 2026 03:14:42 +0000 Subject: [PATCH 2/2] docs: traps, fab 1.1.1+keel1 has the stock unit phase, not none The table said the product.mk of fab 1.1.1+keel1 (b07a733, md5 c04cb601) has no unit phase. It has one, the stock one: the "apply the product-local units" block after the common removelists, byte for byte as in v1.1.1. The only difference from stock is SOURCE_DATE_EPOCH. Measured with `git show b07a733:share/product.mk` in Keel-Linux/fab and a diff against v1.1.1. The md5 values in the table were all rechecked and are right: 0657df1a in the local tkldev container (fab 1.1.1), c04cb601 at b07a733, a06bfe03 on the build host (fab 1.1.1+keel2, identical to fab HEAD). The Fix paragraph still holds: 1.1.1+keel1 does not carry the before-the-removelists order. The same wrong reading ("no unit phase in it at all") is in a comment on keel-core#9; the entry repeated it from there. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01SfWQScmDZ94KCS5DMYrfe6 --- docs/traps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/traps.md b/docs/traps.md index 24fb6cd..8187648 100644 --- a/docs/traps.md +++ b/docs/traps.md @@ -341,7 +341,7 @@ the nearer one answers a question about the other. Measured 2026-09-28: | Machine | fab | `product.mk` md5 | Unit phases in `root.patched/body` | | --- | --- | --- | --- | | local `tkldev` container | `1.1.1`, stock | `0657df1a` | one, after the common removelists | -| fab `1.1.1+keel1` (b07a733) | `1.1.1+keel1` | `c04cb601` | none | +| fab `1.1.1+keel1` (b07a733) | `1.1.1+keel1` | `c04cb601` | one, after the common removelists, as in stock (the file differs from stock only in `SOURCE_DATE_EPOCH`) | | build host | `1.1.1+keel2` | `a06bfe03` | three (overlays, conf scripts, removelists), before the common removelists | **Fix.** Take the reading from the machine that builds, and name the fab