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.py — check_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
Release Impact
The honesty page is the one the application points users at, and nothing
currently stops a stale copy of it being published.
Problem
Two pages are generated from the MeshBench repository and both had drifted a
long way without anything noticing.
gen.py'scheck_synced()refuses to build when a generated page is behind itssource — but only when a sibling
../meshcoresimcheckout is reachable:.github/workflows/pages.ymlnever checks out the code repository, so on therunner 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:
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.mdis the honesty page — the one the application itselfpoints 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.py—check_synced().github/workflows/pages.yml— build job, no second checkoutpages/what-it-does-not-do.md,pages/reference-control.md— the generated pagestools/sync-limits.py,tools/sync-verbs.pyRecommended approach
Make the check able to run where it matters. Either check the code repository
out in
pages.ymlas a second step with a deploy key and let the existing guardwork, 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
sibling checkout
Release Impact
The honesty page is the one the application points users at, and nothing
currently stops a stale copy of it being published.