fix(ci): the doc gate could not see a page it had just created - #251
Draft
Denis-hamon wants to merge 2 commits into
Draft
fix(ci): the doc gate could not see a page it had just created#251Denis-hamon wants to merge 2 commits into
Denis-hamon wants to merge 2 commits into
Conversation
`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
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The gate could not see a page it had just created
make docrunsdocgen, which writes one markdown page per cobra command. Thecheck that follows was
git diff --exit-code, andgit diffreports trackedfiles only. A brand new command therefore produced a brand new file, which is
untracked, which the check cannot see.
That is not a hypothetical:
logoutshipped in #228 and its page has never been in the repository. Thegate was green on the pull request that added it, and has been green on every
pull request since.
The fix
git status --porcelainreports untracked files too, which is the whole pointof 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
mainis in today:The step was left unscoped rather than narrowed to
doc/. Scoping readscleaner, but
git diff --exit-codealso happened to catch ago.mod/go.sumdrift left by the
go get ./...step above it, and narrowing the check wouldhave 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.doc/ovhcloud.md, next tologin.One thing this does not fix, reported rather than decided
make docends withgit checkout doc/ovhcloud.md, so the generated index isdiscarded and the written one is maintained by hand. Nothing keeps it in sync,
and four commands are missing from it:
A check that every top-level page is referenced in the index would catch this,
and would have caught
logouttwice over. It is not in this pull requestbecause whether
completionbelongs in a hand-curated index is an editorialcall for the maintainers, not a mechanical one.