claudiomaradonna/castrum
1
0
Fork 0
Code Issues Pull requests Activity

docs: correct stale comments and the one-off rule #31

Merged
claudiomaradonna merged 1 commit from docs/stale-comments into main 2026-10-08 11:03:32 +02:00
Conversation 0 Commits 1 Files changed 5 +15 -18
motoko commented 2026-10-08 09:52:33 +02:00
Collaborator
Copy link

Why

The docs audit left three stale comments and a fail message that were out of its scope, because changing a template rewrites the file on hosts. The warden removal also showed that the rule "a commit body carries a one-off step on the controller" misses host-side steps.

What changed

  • hardening-basic's 99-protect-links.conf: the read-back lives in tasks/sysctl.yml, not tasks/main.yml; the key counts and the one-host anecdote go, as they already did in the README.
  • ai-stack's compose.yml.j2: the /config mount is "the role's earlier layout", not "pre-v4.9, kept through migration".
  • traefik-routes' fail message: "typically a network mount", not "on this estate".
  • CONTRIBUTING and ADVANCED_USAGE: a commit body carries any one-off step a change needs, on the controller or on its hosts.

Verification

  • Renders before and after differ in comment lines only, for both templates. .env is identical.
  • make check passed and every link resolves.

Risks and follow-ups

  • On the next run, every Linux host rewrites /etc/sysctl.d/99-protect-links.conf and the ai_mainframes host rewrites compose.yml, each reporting one change. No key or service changes: the sysctl apply and read-back run on every run anyway, and a comment-only compose change recreates no container.
  • compose.yml.j2 is also edited by #30, in other lines; whichever merges second needs a rebase.
## Why The docs audit left three stale comments and a fail message that were out of its scope, because changing a template rewrites the file on hosts. The warden removal also showed that the rule "a commit body carries a one-off step on the controller" misses host-side steps. ## What changed - hardening-basic's `99-protect-links.conf`: the read-back lives in `tasks/sysctl.yml`, not `tasks/main.yml`; the key counts and the one-host anecdote go, as they already did in the README. - ai-stack's `compose.yml.j2`: the `/config` mount is "the role's earlier layout", not "pre-v4.9, kept through migration". - traefik-routes' fail message: "typically a network mount", not "on this estate". - CONTRIBUTING and ADVANCED_USAGE: a commit body carries any one-off step a change needs, on the controller or on its hosts. ## Verification - Renders before and after differ in comment lines only, for both templates. `.env` is identical. - `make check` passed and every link resolves. ## Risks and follow-ups - On the next run, every Linux host rewrites `/etc/sysctl.d/99-protect-links.conf` and the ai_mainframes host rewrites `compose.yml`, each reporting one change. No key or service changes: the sysctl apply and read-back run on every run anyway, and a comment-only compose change recreates no container. - `compose.yml.j2` is also edited by #30, in other lines; whichever merges second needs a rebase. 
Three comments and a message carried stale or site-specific wording:
- hardening-basic's 99-protect-links.conf named tasks/main.yml for the
  read-back, which lives in tasks/sysctl.yml, and counted its keys and
  told one host's anecdote, as the README no longer does;
- ai-stack's compose.yml.j2 called the /config mount the "pre-v4.9"
  layout to keep "through migration";
- traefik-routes' fail message said "on this estate".

Both templates render onto hosts: the next run rewrites
/etc/sysctl.d/99-protect-links.conf on every Linux host and
/opt/ai-stack/compose.yml on the ai_mainframes host, reporting one
change each. Renders before and after differ in comment lines only, so
no key or service changes; the sysctl apply and read-back already run
on every run, and a comment-only compose change recreates no container.

CONTRIBUTING and ADVANCED_USAGE now say a commit body carries any
one-off step a change needs, on the controller or on its hosts, as the
warden removal's cleanup steps showed (the user's decision).
motoko force-pushed docs/stale-comments from 0957ef1a20 to 7be4afcc92 2026-10-08 10:56:26 +02:00 Compare
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
claudiomaradonna/castrum!31
No description provided.