2026-08-31 20:48:58 +00:00
1 changed files with 37 additions and 0 deletions
@@ -63,6 +63,43 @@ protects nobody, and it is the failure this project keeps repeating — sealed
 rosters, group names and delivery capabilities all landed in the engine well
 before any UI called them. An issue that only closes half of that is not closed.

+### A doc change that crosses repositories
+
+Several pages here are generated from markdown that lives in `flamenet-e2e`
+(`/spec`, `/self-hosting`, `/audit`, `/security` and others). `Scripts/check-doc-pages.py`
+compares each page against its source **as it stands on `flamenet-e2e` main**,
+which it clones when the job runs.
+
+🔴 **That means a cross-repo doc change makes this repository's `main` red for a
+while, and the guard is right to say so.** A regenerated page can only match the
+new hash after the source is on e2e main, so between "source lands" and
+"regeneration lands" the served page genuinely is stale. Sequence that works:
+
+1. Merge the source change in `flamenet-e2e`.
+2. Immediately run `Scripts/build-doc-pages.sh` here and merge the result.
+3. Deploy, because the pages ship inside the relay image.
+
+⚠️ Do not shorten step 2 by making the job `allow_failure` or skipping it on
+`main`. A stale `/self-hosting` was served for a day telling people to run a
+command that did not work; the guard exists because of that, and a green that
+means nothing is how it comes back.
+
+⚠️ **The same failure has a second cause, and the fix is the opposite one.** If
+your branch was cut before somebody else's regeneration landed, it carries the
+old pages while the source has moved — identical message, but running the
+generator produces no diff and leaves you stuck. Merge `main` in instead. Tell
+the two apart by asking whether `main` already has a newer page than your branch:
+
+```bash
+git fetch && git log --oneline HEAD..origin/main -- Resources/Views/
+```
+
+Anything listed there means it is staleness against `main`, not against the
+source.
+
+⚠️ A slow queue makes this window long rather than momentary — the first time it
+happened, a two-minute gap became most of an hour. See the issues labelled `ops`.
+
 ### What an issue should carry

 The evidence, not the impression. A path and line, a query and its output, a