Skip to content

ci: make the docs agree with the binary, since reading has not stuck - #73

Merged
lex00 merged 1 commit into
mainfrom
docs-drift-guard
Aug 3, 2026
Merged

ci: make the docs agree with the binary, since reading has not stuck#73
lex00 merged 1 commit into
mainfrom
docs-drift-guard

Conversation

@lex00

@lex00 lex00 commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

Closes #68. Ticks another of #54's items, this one for good rather than until next time.

#54 lists README-versus-docs drift as open with the note "they have drifted before". They had, twice, and both times it was closed by reading. The last one was -serve-sts — named in four doc pages and in no README, while being the flag that decides whether the KubeMicroVM operator starts at all.

What it checks

Only things with a single right answer:

  • every flag the docs name is a flag the binary has
  • every flag the binary has is named somewhere in the docs
  • the operation totals the prose claims match what routes.go routes
  • api-surface.md's per-family counts sum to that total — two numbers that are each individually plausible and do not add up is exactly the drift nobody notices

Deliberately not checked: that the README repeats what the docs say. It does not, on purpose — after #72 the README is a lead-in and docs/using-it.md is the reference. A parity rule between them would fight that on every commit.

What running it found

Three flags with no documentation anywhere: -addr, -log-level, -version. Documented rather than exempted, which is how the whole flag surface ended up in one table for the first time.

Verified failing in both directions

$ # add a flag to the binary, document nothing
docs-consistency: the binary has -not-documented-anywhere and no doc page names it

$ # add a row for a flag that does not exist
docs-consistency: docs name a flag the binary does not have: -a-flag-that-does-not-exist

#54 lists README-versus-docs drift as an open item with the note "they have
drifted before". They had, twice, and both times it was closed by reading.
The last one was -serve-sts, named in four doc pages and in no README while
being the flag that decides whether the KubeMicroVM operator starts at all.

So this checks the part with a single right answer. Every flag the docs
name is one the binary has; every flag the binary has is named somewhere;
the operation totals the prose claims match what routes.go routes; and
api-surface.md's per-family counts sum to that total — two numbers that are
each individually plausible and do not add up is exactly the drift nobody
notices.

Deliberately not checked: that the README repeats what the docs say. It
does not, on purpose — the README is a lead-in and docs/using-it.md is the
reference, and a parity rule between them would fight that on every commit.

Running it found three flags with no documentation at all: -addr,
-log-level and -version. Documented rather than exempted, which is how the
whole flag surface ended up in one table for the first time.

Verified failing in both directions — a flag added to the binary with no
row, and a row naming a flag that does not exist.
@lex00
lex00 merged commit 92a07d2 into main Aug 3, 2026
5 checks passed
@lex00
lex00 deleted the docs-drift-guard branch August 3, 2026 04:15
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.

CI should catch README-versus-docs drift, since closing it by hand has not stuck

1 participant