Write down that a cross-repo doc change reddens main #72

2026-08-31T19:32:09Z

paulhitt commented

2026-08-31 19:32:09 +00:00

(Migrated from gitlab.com)

Closes #10

main went red at 0daa4225 for a reason nobody got wrong — the page really was
stale:

doc-pages FAILED
  self-hosting.leaf  from flamenet-e2e/SELF-HOSTING.md  (a4ed8fd6… != 0f36788a…)

/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 — #6 is what made a two-minute
gap into most of an hour.

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

allow_failure: true on main, or skipping the job there, converts an honest red
into a green that means nothing — the same pattern taken out of the Android suite
today (18 tests reporting 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.

Closes #10 `main` went red at `0daa4225` for a reason nobody got wrong — the page really was stale: ``` doc-pages FAILED self-hosting.leaf from flamenet-e2e/SELF-HOSTING.md (a4ed8fd6… != 0f36788a…) ``` `/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* — #6 is what made a two-minute gap into most of an hour. 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 `allow_failure: true` on main, or skipping the job there, converts an honest red into a green that means nothing — the same pattern taken out of the Android suite today (18 tests reporting 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.

paulhitt commented

2026-08-31 20:22:37 +00:00

(Migrated from gitlab.com)

⚠️ First pipeline failed, and the failure is the ticket demonstrating itself.

doc-pages FAILED
  self-hosting.leaf  from flamenet-e2e/SELF-HOSTING.md  (a4ed8fd6… != 0f36788a…)
  spec.leaf          from flamenet-e2e/docs/SPEC.md     (41002a1e… != 50c7c8d5…)

This branch was cut from main before !7 and !8 landed, so it carried the
pre-regeneration pages while e2e main had already moved. Merged main in; the
guard is clean:

9 generated pages match their sources

🔴 Worth noting rather than quietly fixing: this is a second shape of the same
hazard, and the one this MR-s text does not cover. #10 describes the window
between a source merging and its regeneration merging. This was a branch going
stale against a regeneration that had already happened — same guard, same
message, different cause, and the fix is git merge main rather than
build-doc-pages.sh.

The rule as written says to regenerate. Somebody hitting this variant would run
the generator, get no diff, and be stuck. Adding that to the text.

⚠️ First pipeline failed, and the failure is the ticket demonstrating itself. ``` doc-pages FAILED self-hosting.leaf from flamenet-e2e/SELF-HOSTING.md (a4ed8fd6… != 0f36788a…) spec.leaf from flamenet-e2e/docs/SPEC.md (41002a1e… != 50c7c8d5…) ``` This branch was cut from `main` **before** !7 and !8 landed, so it carried the pre-regeneration pages while e2e main had already moved. Merged main in; the guard is clean: ``` 9 generated pages match their sources ``` 🔴 Worth noting rather than quietly fixing: this is a **second shape** of the same hazard, and the one this MR-s text does not cover. #10 describes the window between a source merging and its regeneration merging. This was a branch going stale against a regeneration that had already happened — same guard, same message, different cause, and the fix is `git merge main` rather than `build-doc-pages.sh`. The rule as written says to regenerate. Somebody hitting this variant would run the generator, get no diff, and be stuck. Adding that to the text.

paulhitt commented

2026-08-31 20:22:38 +00:00

(Migrated from gitlab.com)

added 7 commits

329e5394...f72653af - 6 commits from branch main
5e27624f - Merge main: pick up the regenerated doc pages

Compare with previous version

added 7 commits <ul><li>329e5394...f72653af - 6 commits from branch <code>main</code></li><li>5e27624f - Merge main: pick up the regenerated doc pages</li></ul> [Compare with previous version](/paulhitt/flamenet-relay/-/merge_requests/9/diffs?diff_id=1995197304&start_sha=329e539461eaa21f6857840413488e1cb3cdc007)

paulhitt commented

2026-08-31 20:22:56 +00:00

(Migrated from gitlab.com)

added 1 commit

59b2e569 - The rule needed the other cause too

Compare with previous version

added 1 commit <ul><li>59b2e569 - The rule needed the other cause too</li></ul> [Compare with previous version](/paulhitt/flamenet-relay/-/merge_requests/9/diffs?diff_id=1995197784&start_sha=5e27624fc1e0a30faef0548fc4c81d7a52dcfc75)

paulhitt commented

2026-08-31 20:48:58 +00:00

(Migrated from gitlab.com)

mentioned in commit 4d34a15cdc

mentioned in commit 4d34a15cdc826d71bd38abe0d2e940c3c8912704

paulhitt (Migrated from gitlab.com) merged commit 4d34a15cdc into main

2026-08-31 20:48:58 +00:00

paulhitt commented

2026-09-09 18:59:23 +00:00

(Migrated from gitlab.com)

changed the description

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: extant2000/flamenet-relay#72