Skip to content

docs(readme): stop teaching the observe that cost #486 - #645

Merged
haribo merged 1 commit into
developfrom
docs/642-readme-teaches-a-defect
Sep 10, 2026
Merged

docs(readme): stop teaching the observe that cost #486#645
haribo merged 1 commit into
developfrom
docs/642-readme-teaches-a-defect

Conversation

@haribo

@haribo haribo commented Sep 10, 2026

Copy link
Copy Markdown
Owner

Summary

Three corrections to the page a newcomer reads first, each verified against the source before
being changed (audit in #642).

  • The def example no longer teaches report a purged package as absent in apt.install #486. It asked dpkg -s "$pkg", which exits 0 for a
    package removed without --purge. It now carries apt.install's real question, plus the
    paragraph that makes it a lesson rather than a snippet: the wrong answer was stable, so
    re-running agreed with itself and only the machine said otherwise.
  • --json, -v, --parallel, --limit are in the flag table, with one line saying which
    command takes what. --check stays undocumented on purpose — it is registered with an empty
    usage string only to tell an operator the flag is now --dry-run (ADR-0035).
  • The secrets note said "at-rest secrecy is not yet solved"; ADR-0025 solved it. It now
    states the limit that is left — root on the target reads the job file and the process
    environment in real time — and keeps ADR-0025 §3's /tmp fallback, so it is not overclaiming
    either.

The issue proposed command -v for the example. That is a second wrong question: the parameter
is a package name, so it would work for curl and never converge for ca-certificates.

Test plan

The example was extracted from the README verbatim into a project and run against a real
Debian target — nothing validates README snippets today, so it was worth doing:

1. dry-run, host without nano    readme.install(pkg=nano) would.installed
2. apply                         readme.install(pkg=nano) ok.installed
3. re-apply                      readme.install(pkg=nano) ok.already
4. apt-get remove nano (no --purge)
   dpkg -s still exits 0 (the trap)      dpkg-query → deinstall ok config-files
5. dry-run again                 readme.install(pkg=nano) would.installed

Step 5 is the point: the old spelling would have said already there.

The flag claim is checked by loop against cmd/shellf/main.go, not by eye — every flag
runCmd, statusCmd and cleanCmd register now appears in README.md, check excepted.
grep -c "at-rest secrecy is not yet solved" README.md → 0.

go test ./..., test/lint.sh and test/changelog-rule.sh green.

Not here

README.md:39 tells a newcomer to download v0.10.0, three releases back. Flagged in #642's
audit, left for its own issue.

Closes #642

@haribo
haribo merged commit 6616a2f into develop Sep 10, 2026
8 checks passed
@haribo
haribo deleted the docs/642-readme-teaches-a-defect branch September 10, 2026 07:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant