Skip to content

[Docs] The generated-page staleness guard cannot run in CI #19

Description

@A13xB0

Problem

Two pages are generated from the MeshBench repository and both had drifted a
long way without anything noticing.

gen.py's check_synced() refuses to build when a generated page is behind its
source — but only when a sibling ../meshcoresim checkout is reachable:

if not os.path.exists(src):
    continue

.github/workflows/pages.yml never checks out the code repository, so on the
runner that condition is always false and the guard is a no-op. The build passes
and the stale page publishes.

Run locally against a current checkout, the drift was substantial:

pages/what-it-does-not-do.md | 300 ++++++++++++++++++++++++++++++++++++-----
1 file changed, 297 insertions(+), 3 deletions(-)
pages/reference-control.md   |  16 ++++++++--------

Both have now been resynced, so this issue is about the guard rather than about
the current content.

Why it matters

what-it-does-not-do.md is the honesty page — the one the application itself
points users at, and the one the site's own navigation places directly under
Getting started because "a reader who cannot find the limits cannot use any
other number on the site". It is the single worst page to publish stale, and it
is the page with the least protection.

The mechanism guarantees the failure is silent and one-directional: a developer
with a sibling checkout is blocked from building, so the drift is invisible to
exactly the person who could fix it, while CI cheerfully publishes.

Location

  • gen.pycheck_synced()
  • .github/workflows/pages.yml — build job, no second checkout
  • pages/what-it-does-not-do.md, pages/reference-control.md — the generated pages
  • tools/sync-limits.py, tools/sync-verbs.py

Recommended approach

Make the check able to run where it matters. Either check the code repository
out in pages.yml as a second step with a deploy key and let the existing guard
work, or record the source's content hash in the generated page and fail the
build when the committed page does not match the hash it claims — which needs no
second checkout at all.

Failing loudly when the source is unreachable is not enough on its own, because
that is the normal state on the runner; the check needs something it can compare
against.

Acceptance criteria

  • A stale generated page fails the build on CI, not only on a machine with a
    sibling checkout
  • The failure names which page is stale and which command regenerates it
  • Both generated pages are verified current as part of the release
  • Documentation matches current implementation
  • Links validated
  • Documentation site builds successfully

Release Impact

The honesty page is the one the application points users at, and nothing
currently stops a stale copy of it being published.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Before First ReleaseMust be resolved before the first public releaseP1High: strongly recommended before releasedocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions