Hygiene check reads the manual PDF as text: the next release that changes the manual will fail CI #3

New Issue

2026-10-14T04:30:53Z

ekklesia-bot commented

2026-10-14 04:30:53 +00:00

Summary

CI's hygiene check, git diff --check "$base" HEAD in tools/check.sh:103, reads docs/manual/build/classroom-manual.pdf as text. A PDF's cross-reference table ends every entry with a space by specification:

0000007188 00000 n ␠

So any manual change that moves content rewrites those lines, each one is reported as trailing whitespace, and checks fails. The repository has no .gitattributes.

The release process requires rebuilding the manual in every release commit (echo 0.2.6.7 > VERSION && tools/build-manual), so this will block a release pull request as soon as its manual actually changes.

Evidence

Replaying the check on the last six commits that touched the PDF. All predate CI (added 2026-09-29), so nobody has seen it fail yet:

Commit		Lines flagged
`1a338b2`	release: 0.2.6.6	0 (only the revision date changed)
`23194a0`	release: 0.2.6.4	7
`5fef4e0`	release: 0.2.6.3	26
`550c0bf`	release: 0.2.6.2	6
`6946bae`	release: 0.2.6.1	6
`f2942a2`	docs: one manual, …	27

(git diff --check <c>^ <c> -- docs/manual/build/classroom-manual.pdf | grep -c "trailing whitespace".) Running tools/check.sh --base <root commit> locally fails the same way, along with two small real ones: tests/test-classroom-parent-call.sh:130 (trailing space) and tools/lab/kwin-script:37 (blank line at EOF).

Suggested fix

Add a .gitattributes:

*.pdf binary

That makes git treat the PDF as binary for diffs, including --check, and doesn't change the bytes. Alternatively, exclude docs/manual/build/ from the hygiene diff the way the CI workflow already excludes it from the "tree unchanged" test, but the attribute is simpler and also stops PDF noise in reviews. While there, fix the two genuine whitespace issues above so a full-history check is clean.

Not checked

Other generated binaries the repository might commit later (docs/screenshots is PNG, which git already detects as binary).

Found by Claude during a review of Classroom_Desktop's CI, 2026-10-14 (found-by-claude).

## Summary CI's hygiene check, `git diff --check "$base" HEAD` in `tools/check.sh:103`, reads `docs/manual/build/classroom-manual.pdf` as **text**. A PDF's cross-reference table ends every entry with a space by specification: ``` 0000007188 00000 n ␠ ``` So any manual change that moves content rewrites those lines, each one is reported as `trailing whitespace`, and `checks` fails. The repository has no `.gitattributes`. The release process requires rebuilding the manual in every release commit (`echo 0.2.6.7 > VERSION && tools/build-manual`), so this will block a release pull request as soon as its manual actually changes. ## Evidence Replaying the check on the last six commits that touched the PDF. All predate CI (added 2026-09-29), so nobody has seen it fail yet: | Commit | | Lines flagged | |---|---|---| | `1a338b2` | release: 0.2.6.6 | 0 (only the revision date changed) | | `23194a0` | release: 0.2.6.4 | 7 | | `5fef4e0` | release: 0.2.6.3 | 26 | | `550c0bf` | release: 0.2.6.2 | 6 | | `6946bae` | release: 0.2.6.1 | 6 | | `f2942a2` | docs: one manual, … | 27 | (`git diff --check <c>^ <c> -- docs/manual/build/classroom-manual.pdf | grep -c "trailing whitespace"`.) Running `tools/check.sh --base <root commit>` locally fails the same way, along with two small real ones: `tests/test-classroom-parent-call.sh:130` (trailing space) and `tools/lab/kwin-script:37` (blank line at EOF). ## Suggested fix Add a `.gitattributes`: ```gitattributes *.pdf binary ``` That makes git treat the PDF as binary for diffs, including `--check`, and doesn't change the bytes. Alternatively, exclude `docs/manual/build/` from the hygiene diff the way the CI workflow already excludes it from the "tree unchanged" test, but the attribute is simpler and also stops PDF noise in reviews. While there, fix the two genuine whitespace issues above so a full-history check is clean. ## Not checked Other generated binaries the repository might commit later (`docs/screenshots` is PNG, which git already detects as binary). --- _Found by Claude during a review of Classroom_Desktop's CI, 2026-10-14 (`found-by-claude`)._

ekklesia-bot referenced this issue

2026-10-14 04:31:17 +00:00

Release pipeline is not set up on the Zayin Gitea: no release records, admin checklist still open #4

ekklesia-bot referenced this issue

2026-10-14 04:35:21 +00:00

State of Classroom_Desktop (review 2026-10-14) and a suggested order of work #6

ekklesia-bot added the found-by-claude label 2026-10-14 04:40:48 +00:00

Sign in to join this conversation.