docs: cut the essays out of the manifests I wrote today #678

2026-08-27T19:37:49Z

claude-bot commented

2026-08-27 19:37:49 +00:00

Erster Schnitt, und zwar an dem, was ich heute selbst eingebaut habe: zwei verworfene Hypothesen im securityContext des smartctl-Exporters, eine zwanzigzeilige „CANONICAL NOTE" im Paperless-ExternalSecret, die Entstehungsgeschichte einer Alarmschwelle. Das ist Herleitung, keine Konfiguration.

160 Zeilen raus, 30 rein. Nichts am Verhalten geändert, beide Manifeste bestehen weiter --dry-run=server.

Das Kriterium, das ich angewandt habe — und das für den Rest zur Diskussion steht:

Ein Kommentar bleibt, wenn er ändert, was jemand tut, der diese Zeile bearbeitet: eine Eigenheit des Werkzeugs, eine Falle, ein Verweis auf ein Issue.
Er geht, wenn er erzählt, wie eine Erkenntnis zustande kam, eine Messung wiederholt oder einen Wert nachträglich rechtfertigt.
Test: könnte die umgebende Konfiguration sich ändern und den Kommentar still falsch machen?

Beispiel für „bleibt": „Kein --smartctl.device: Gerätenamen sind über die Maschinen nicht stabil." Beispiel für „geht": die drei Absätze darüber, wie ich das herausgefunden habe.

description:-Felder in Alarmregeln habe ich gekürzt, nicht entfernt — das sind keine Kommentare, sondern der Text, den jemand liest, wenn der Alarm feuert. Ein Aufsatz ist dort schlimmer als anderswo.

Zum Rest des Repos: rund 8.600 Kommentarzeilen, davon 88 Dateien über 25 Zeilen. Spitzenreiter:

559  apps/authentik/blueprints-configmap.yaml
264  talos/patches/cilium-cni.yaml
224  talos/cilium.yaml
224  infrastructure/rook-ceph-cluster/cephcluster.yaml
201  apps/otbr/deployment.yaml
196  apps/trmnl/renderer.yaml

Das gehe ich nicht in einem Rutsch durch. Vieles davon ist tragende Warnung, keine Erzählung — etwa der Hinweis in talos/patches/k8s-1.yaml, dass ein breiter Disk-Selektor das OSD-Laufwerk trifft und der Installer es formatiert. So etwas zu kürzen wäre ein Rückschritt.

Vorschlag: bereichsweise in Chargen, talos/ zuerst, dann infrastructure/, dann apps/ — jeweils ein PR, damit du das Kriterium an einem überschaubaren Diff korrigieren kannst, bevor es auf 88 Dateien angewandt wird.

Erster Schnitt, und zwar an dem, was ich heute selbst eingebaut habe: zwei verworfene Hypothesen im `securityContext` des smartctl-Exporters, eine zwanzigzeilige „CANONICAL NOTE" im Paperless-ExternalSecret, die Entstehungsgeschichte einer Alarmschwelle. Das ist Herleitung, keine Konfiguration. **160 Zeilen raus, 30 rein.** Nichts am Verhalten geändert, beide Manifeste bestehen weiter `--dry-run=server`. Das Kriterium, das ich angewandt habe — und das für den Rest zur Diskussion steht: > Ein Kommentar **bleibt**, wenn er ändert, was jemand tut, der diese Zeile bearbeitet: eine Eigenheit des Werkzeugs, eine Falle, ein Verweis auf ein Issue. > Er **geht**, wenn er erzählt, wie eine Erkenntnis zustande kam, eine Messung wiederholt oder einen Wert nachträglich rechtfertigt. > Test: könnte die umgebende Konfiguration sich ändern und den Kommentar still falsch machen? Beispiel für „bleibt": *„Kein `--smartctl.device`: Gerätenamen sind über die Maschinen nicht stabil."* Beispiel für „geht": die drei Absätze darüber, wie ich das herausgefunden habe. `description:`-Felder in Alarmregeln habe ich **gekürzt, nicht entfernt** — das sind keine Kommentare, sondern der Text, den jemand liest, wenn der Alarm feuert. Ein Aufsatz ist dort schlimmer als anderswo. --- **Zum Rest des Repos:** rund **8.600 Kommentarzeilen**, davon **88 Dateien über 25 Zeilen**. Spitzenreiter: ``` 559 apps/authentik/blueprints-configmap.yaml 264 talos/patches/cilium-cni.yaml 224 talos/cilium.yaml 224 infrastructure/rook-ceph-cluster/cephcluster.yaml 201 apps/otbr/deployment.yaml 196 apps/trmnl/renderer.yaml ``` Das gehe ich nicht in einem Rutsch durch. Vieles davon ist tragende Warnung, keine Erzählung — etwa der Hinweis in `talos/patches/k8s-1.yaml`, dass ein breiter Disk-Selektor das OSD-Laufwerk trifft und der Installer es formatiert. So etwas zu kürzen wäre ein Rückschritt. Vorschlag: bereichsweise in Chargen, `talos/` zuerst, dann `infrastructure/`, dann `apps/` — jeweils ein PR, damit du das Kriterium an einem überschaubaren Diff korrigieren kannst, bevor es auf 88 Dateien angewandt wird.

claude-bot added 1 commit 2026-08-27 19:37:49 +00:00

docs: cut the essays out of the manifests I wrote today

ci/woodpecker/pr/ci-scripts-test Pipeline was successful

Details

ci/woodpecker/pr/ci-manifests-test Pipeline was successful

Details

ci/woodpecker/pr/pr-review Pipeline was successful

Details

da1482e33f

Config files were carrying investigation write-ups: two ruled-out hypotheses in
the smartctl-exporter securityContext, a twenty-line canonical note on the
Hetzner credential, the history of an alert threshold. That is derivation, not
configuration, and it belongs where it does not rot — the commit message for how
we got here, the wiki for what holds.

The distinction this applies: a comment stays if it changes what someone editing
that line would do — a constraint of the tool, a trap, a pointer to an issue. It
goes if it narrates how a conclusion was reached, restates a measurement, or
justifies a value after the fact. The test is whether the surrounding config
could change and leave the comment quietly wrong.

160 lines out, 30 in. Nothing behavioural changed; both manifests still pass a
server-side dry run.

Alert descriptions were tightened rather than removed. Those are not comments —
they are what someone reads when paged, and an essay is worse there than
anywhere.

This covers only what I added today. The repo has roughly 8600 comment lines
with 88 files over 25, and going further needs the criterion above agreed
first — much of that volume is load-bearing warning rather than narration.

review-bot reviewed

2026-08-27 19:39:48 +00:00

review-bot left a comment

🤖 Automated review — model claude-haiku-4-5-20251001 (complexity: trivial), commit da1482e33f11a414a0b5470912bd8bb39b958be7.

Advisory review by the review-bot pipeline. It never approves; a human merges. Push new commits to get a fresh review.

Summary

This PR removes verbose explanatory comments from five manifest files (160 lines deleted, 30 retained), applying a clear criterion: keep comments that guide future editors (tool quirks, traps, issue references) and remove those that explain how insights were discovered or justify values after the fact. All manifests pass --dry-run=server and no configuration logic changes. No blocking issues.

🟢 Observations

The comment removals are consistent with the stated criterion and well-scoped:

ha-pg-hetzner-creds-externalsecret.yaml: Removed historical narrative of a rejected approach; kept the actionable namespace allowlist warning.
prometheusrule-disk-wear.yaml: Shortened explanatory prose in alert descriptions and removed multi-line justifications of threshold choices and timing parameters. Retained brief, actionable comments ("Long for because wear is monotonic and cannot flap").
smartctl-exporter-servicemonitor.yaml: Removed rationale for scraping frequency; kept the relabeling logic intact.
smartctl-exporter.yaml: Removed a comprehensive 32-line explanation of why elevated privileges are required and why narrower settings failed. Replaced with a 3-line pointer to commit history. This is the most aggressive cut; the removed comment encoded valuable defensive reasoning.
hetzner-creds-externalsecret.yaml: Removed the "CANONICAL NOTE" — a 24-line institutional explanation of credential path consolidation history. Kept the concise current-state summary.

The batch approach in the PR body (talos/ → infrastructure/ → apps/) is sensible for reviewability and criterion refinement.

🟡 Suggestions

Commit message discipline: The smartctl-exporter.yaml change relies on readers finding detailed reasoning in commit history. Ensure this PR's commit message (or a follow-up) captures the full reasoning about why privileged: true is necessary and why narrower alternatives (CAP_SYS_ADMIN + CAP_SYS_RAWIO, seccomp, device cgroup) don't work. This is the kind of reasoning that future maintainers may need to revisit.
Defensive vs. explanatory: Comments encoding defensive decisions or architectural trade-offs (e.g., "we tried X and it failed because Y") are sometimes worth keeping if the trade-off is non-obvious or could be reconsidered. Consider whether any of the removed comments fall into this category and whether a brief pointer (e.g., "tried narrower settings, see #xyz") might be worth retaining instead of fully removing.

Tests

The author ran --dry-run=server on both modified ExternalSecret and DaemonSet manifests — a good validation that syntax and semantic correctness are preserved. No existing tests are affected (these are configuration-only changes).

Recommendation

Looks reasonable — no blocking issues; suggestions above are optional refinements to guard against knowledge loss.

🤖 **Automated review** — model `claude-haiku-4-5-20251001` (complexity: trivial), commit `da1482e33f11a414a0b5470912bd8bb39b958be7`. > Advisory review by the `review-bot` pipeline. It never approves; a human merges. Push new commits to get a fresh review. --- ## Summary This PR removes verbose explanatory comments from five manifest files (160 lines deleted, 30 retained), applying a clear criterion: keep comments that guide future editors (tool quirks, traps, issue references) and remove those that explain how insights were discovered or justify values after the fact. All manifests pass `--dry-run=server` and no configuration logic changes. No blocking issues. ## 🟢 Observations The comment removals are consistent with the stated criterion and well-scoped: - **ha-pg-hetzner-creds-externalsecret.yaml**: Removed historical narrative of a rejected approach; kept the actionable namespace allowlist warning. - **prometheusrule-disk-wear.yaml**: Shortened explanatory prose in alert descriptions and removed multi-line justifications of threshold choices and timing parameters. Retained brief, actionable comments ("Long `for` because wear is monotonic and cannot flap"). - **smartctl-exporter-servicemonitor.yaml**: Removed rationale for scraping frequency; kept the relabeling logic intact. - **smartctl-exporter.yaml**: Removed a comprehensive 32-line explanation of why elevated privileges are required and why narrower settings failed. Replaced with a 3-line pointer to commit history. This is the most aggressive cut; the removed comment encoded valuable defensive reasoning. - **hetzner-creds-externalsecret.yaml**: Removed the "CANONICAL NOTE" — a 24-line institutional explanation of credential path consolidation history. Kept the concise current-state summary. The batch approach in the PR body (talos/ → infrastructure/ → apps/) is sensible for reviewability and criterion refinement. ## 🟡 Suggestions 1. **Commit message discipline**: The smartctl-exporter.yaml change relies on readers finding detailed reasoning in commit history. Ensure this PR's commit message (or a follow-up) captures the full reasoning about why `privileged: true` is necessary and why narrower alternatives (CAP_SYS_ADMIN + CAP_SYS_RAWIO, seccomp, device cgroup) don't work. This is the kind of reasoning that future maintainers may need to revisit. 2. **Defensive vs. explanatory**: Comments encoding defensive decisions or architectural trade-offs (e.g., "we tried X and it failed because Y") are sometimes worth keeping if the trade-off is non-obvious or could be reconsidered. Consider whether any of the removed comments fall into this category and whether a brief pointer (e.g., "tried narrower settings, see #xyz") might be worth retaining instead of fully removing. ## Tests The author ran `--dry-run=server` on both modified ExternalSecret and DaemonSet manifests — a good validation that syntax and semantic correctness are preserved. No existing tests are affected (these are configuration-only changes). ## Recommendation Looks reasonable — no blocking issues; suggestions above are optional refinements to guard against knowledge loss.

k.renner merged commit 9f10ea793d into master

2026-08-28 04:20:34 +00:00

k.renner referenced this issue from a commit

2026-08-28 04:20:35 +00:00

Merge pull request 'docs: cut the essays out of the manifests I wrote today' (#678) from trim-manifest-comments into master

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: konairius/homelab#678