A cross-repo doc change turns main red for the length of the queue #10

New Issue

2026-08-31T19:23:53Z

paulhitt commented

2026-08-31 19:23:53 +00:00

(Migrated from gitlab.com)

main went red at 0daa4225, correctly:

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

The page really was stale. But the sequence that produced it is structural, not a
mistake anyone made twice:

relay!7 merged 18:20; its pipeline queued behind #6
flamenet-e2e!4 merged ~18:55, changing SELF-HOSTING.md
relay's doc-pages job finally ran at 19:03 — and it clones e2e main at
job runtime, which by then had the new source

So a pipeline that would have passed when it was created failed when it ran.

🔴 The window cannot be closed by ordering alone

The guard compares the relay's recorded hash against e2e main. A regenerated
page can only match after the source is on e2e main. So between "source
lands" and "regeneration lands" the relay's main is genuinely red, and that is
the guard telling the truth.

Landing the regeneration promptly keeps it short. #6 makes it long: 23 minutes of
queue turned a two-minute window into most of an hour.

What NOT to do

⚠️ allow_failure: true on main, or skipping the job there. That converts a true
red into a green that means nothing — the same pattern removed from the Android
suite today (paulhitt/flamenet-messenger-android#4, 18 tests reporting PASSED
while running nothing). The guard exists because a stale page stayed served for a
day; weakening it to avoid an honest red would undo the whole point.

Options worth weighing

Write the ordering rule down in CONTRIBUTING.md, next to the tracking
convention: a doc source and its regenerated page live in different
repositories, so land the regeneration immediately after the source and expect
main to be red in between. Cheapest, and honest.
Record the e2e commit in the banner as well as the content hash, so the
failure can say "source moved 3 commits ago" rather than only "hashes differ".
Better diagnostics, same red.
Fix #6, which is what makes the window long enough to notice.

Done when

The rule is written down where somebody will meet it
A cross-repo doc change can be landed without anyone rediscovering this

`main` went red at `0daa4225`, correctly: ``` doc-pages FAILED self-hosting.leaf from flamenet-e2e/SELF-HOSTING.md (a4ed8fd6… != 0f36788a…) ``` The page really was stale. But the sequence that produced it is structural, not a mistake anyone made twice: 1. relay!7 merged 18:20; its pipeline queued behind #6 2. flamenet-e2e!4 merged ~18:55, changing `SELF-HOSTING.md` 3. relay's `doc-pages` job finally ran at 19:03 — and it **clones e2e `main` at job runtime**, which by then had the new source So a pipeline that would have passed when it was created failed when it ran. ### 🔴 The window cannot be closed by ordering alone The guard compares the relay's recorded hash against e2e `main`. A regenerated page can only match **after** the source is on e2e main. So between "source lands" and "regeneration lands" the relay's main is genuinely red, and that is the guard telling the truth. Landing the regeneration promptly keeps it short. #6 makes it long: 23 minutes of queue turned a two-minute window into most of an hour. ### What NOT to do ⚠️ `allow_failure: true` on main, or skipping the job there. That converts a true red into a green that means nothing — the same pattern removed from the Android suite today (paulhitt/flamenet-messenger-android#4, 18 tests reporting PASSED while running nothing). The guard exists because a stale page stayed served for a day; weakening it to avoid an honest red would undo the whole point. ### Options worth weighing - **Write the ordering rule down** in `CONTRIBUTING.md`, next to the tracking convention: a doc source and its regenerated page live in different repositories, so land the regeneration immediately after the source and expect main to be red in between. Cheapest, and honest. - **Record the e2e commit** in the banner as well as the content hash, so the failure can say "source moved 3 commits ago" rather than only "hashes differ". Better diagnostics, same red. - **Fix #6**, which is what makes the window long enough to notice. ### Done when - [ ] The rule is written down where somebody will meet it - [ ] A cross-repo doc change can be landed without anyone rediscovering this

paulhitt commented

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

(Migrated from gitlab.com)

mentioned in merge request !9

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) closed this issue

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: extant2000/flamenet-relay#10