From 329e539461eaa21f6857840413488e1cb3cdc007 Mon Sep 17 00:00:00 2001 From: Paul Hitt Date: Mon, 31 Aug 2026 15:24:33 -0400 Subject: [PATCH 1/2] Write down that a cross-repo doc change reddens main MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `main` went red at 0daa4225 for a reason nobody got wrong: the page really was stale. `/spec` and `/self-hosting` are generated from markdown in flamenet-e2e, and the guard compares each page against that source as it stands on e2e main, cloned when the job runs. So relay!7 was created when it would have passed and ran twenty minutes later, after flamenet-e2e!4 had moved the source underneath it. The window cannot be closed by ordering: a regenerated page can only match the new hash after the source is on e2e main, so between the two merges the served page genuinely is stale and the guard is telling the truth. What it can be is short. The sequence is written down now, with the reason, so the next person meets it as a rule rather than as a surprise on a red pipeline. ⚠️ And a warning against the obvious shortcut. Making the job allow_failure, or skipping it on main, converts an honest red into a green that means nothing — the same pattern taken out of the Android suite today, where eighteen tests reported PASSED while running nothing. The guard exists because a stale /self-hosting was served for a day telling people to run a command that did not work. --- CONTRIBUTING.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59a22cf..f22382d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,6 +63,30 @@ 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. + +⚠️ 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 -- 2.54.0 From 59b2e569f3ab5419955a47a4bc7bf9b846112fbf Mon Sep 17 00:00:00 2001 From: Paul Hitt Date: Mon, 31 Aug 2026 16:22:51 -0400 Subject: [PATCH 2/2] The rule needed the other cause too MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This MR's own first pipeline failed with the message it was written to explain, for a cause it did not cover: the branch was cut before another regeneration landed, so it carried the old pages while the source had moved on. Same guard, same output, and the remedy is the opposite one — `git merge main`, not `build-doc-pages.sh`, which produces no diff and leaves you stuck. A rule that names one of two causes is worse than none, because it sends the reader confidently down the wrong path. Both are written down now, with a command that tells them apart. --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f22382d..6fd9210 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,6 +84,19 @@ new hash after the source is on e2e main, so between "source lands" and 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`. -- 2.54.0