Skip to content

fix(ci): the doc gate could not see a page it had just created - #251

Draft
Denis-hamon wants to merge 2 commits into
ovh:mainfrom
Denis-hamon:fix/doc-gate-sees-new-files
Draft

fix(ci): the doc gate could not see a page it had just created#251
Denis-hamon wants to merge 2 commits into
ovh:mainfrom
Denis-hamon:fix/doc-gate-sees-new-files

Conversation

@Denis-hamon

Copy link
Copy Markdown
Contributor

The gate could not see a page it had just created

make doc runs docgen, which writes one markdown page per cobra command. The
check that follows was git diff --exit-code, and git diff reports tracked
files only
. A brand new command therefore produced a brand new file, which is
untracked, which the check cannot see.

That is not a hypothetical:

$ git ls-tree origin/main doc/ovhcloud_logout.md
$                                   # 935 pages tracked, this one absent

$ make doc && git diff --exit-code ; echo "rc=$?"
rc=0                                # green

$ git status --porcelain
?? doc/ovhcloud_logout.md           # what the gate did not see

logout shipped in #228 and its page has never been in the repository. The
gate was green on the pull request that added it, and has been green on every
pull request since.

The fix

git status --porcelain reports untracked files too, which is the whole point
of the check. The failure now prints what actually changed, so a drift in a
file that is not documentation does not read as a stale doc.

Verified by sabotage — reproducing exactly the state main is in today:

tree state old gate new gate
page generated, tracked green green
page generated, untracked green red

The step was left unscoped rather than narrowed to doc/. Scoping reads
cleaner, but git diff --exit-code also happened to catch a go.mod/go.sum
drift left by the go get ./... step above it, and narrowing the check would
have dropped that with nothing else covering it. Measured: go get ./...
leaves the tree clean today, so the broader check costs nothing.

Also in this commit

  • doc/ovhcloud_logout.md, the page that was missing.
  • Its entry in doc/ovhcloud.md, next to login.

One thing this does not fix, reported rather than decided

make doc ends with git checkout doc/ovhcloud.md, so the generated index is
discarded and the written one is maintained by hand. Nothing keeps it in sync,
and four commands are missing from it:

ovhcloud_browser.md
ovhcloud_completion.md
ovhcloud_logout.md      <- added here
ovhcloud_upgrade.md

A check that every top-level page is referenced in the index would catch this,
and would have caught logout twice over. It is not in this pull request
because whether completion belongs in a hand-curated index is an editorial
call for the maintainers, not a mechanical one.

`git diff --exit-code` reports tracked files only. docgen writes one page per
command, so a new command produces a new file, which is untracked and therefore
invisible to the check: the gate passed while the page was never committed.

That is not hypothetical. `logout` shipped in ovh#228 and its page has never been
in the repository — 935 doc pages tracked, that one absent — and the gate was
green on the pull request that added it. `git status --porcelain` reports
untracked files too, and the failure now prints what actually changed, so a
drift in a file that is not documentation does not read as a stale doc.

Adds the missing page and its entry in the index, which is hand-maintained:
`make doc` reverts doc/ovhcloud.md with `git checkout`, so the generated index
is discarded and nothing keeps the written one in sync.

Signed-off-by: Denis Hamon <denis.hamon@ovhcloud.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Denis-hamon
Denis-hamon requested a review from a team as a code owner August 19, 2026 10:01
@Denis-hamon
Denis-hamon marked this pull request as draft August 20, 2026 13:09
The previous commit fixed one direction: a page docgen creates is untracked, so
`git diff` cannot see it, and `git status --porcelain` can. The other direction
was still open. docgen only ever writes, so a page for a command that has been
renamed or removed stays on disk, tracked, byte-identical — nothing to diff,
nothing to report, gate green forever.

That is not hypothetical. Commit 706d893 "refactor all storage commands" renamed
`cloud storage-file` to `cloud storage file` and `cloud storage-swift` to
`cloud storage swift`. Twenty-one pages of the old naming are still shipped on
main today, documenting commands the binary does not have, and this gate was
green through the rename and through every commit since. They are deleted here,
in the same commit, because the check would otherwise go red on merge.

The fix is to wipe docgen's output before regenerating it, so a page it no
longer produces shows up as deleted. Scoped to `ovhcloud*.md` and not `*.md`:
doc/ also holds pages nobody generates — authentication.md and profiles.md are
written by hand and a blanket wipe would delete them. doc/ovhcloud.md is
generated but curated, and `make doc` already restores it on its last line.

Measured, in both directions and without a pipe: on the tree before this commit,
wiping and regenerating deletes 23 files — the 21 above plus the two hand-written
ones, which is how the scope was settled. After it, the tree is clean. And the
control that matters: with one of those 21 pages put back, the OLD gate reports
green, which is the defect.

Signed-off-by: Denis Hamon <denis.hamon@ovhcloud.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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