diff --git a/docs/product-copy-context.md b/docs/product-copy-context.md index dbebe86..b183e50 100644 --- a/docs/product-copy-context.md +++ b/docs/product-copy-context.md @@ -48,6 +48,29 @@ make ephemeral consumers cheap without making the network absorb the rebuild. statements about the currently running build. - Runtime facts belong on /status; the / page should remain legible, welcoming, and honest about whether it is filling or serving. +- **Do not put process-local counters on a page that describes the run.** + "up N" and "N live events this run" are measured from process start, and the + process currently restarts at every backfill batch boundary. Checked on + experiment 6 at 55.6 h elapsed, with 16,728,092,842 events archived, the + homepage read: + + ``` + up 12m · 289,369 live events this run · 0 listening + ``` + + Both numbers were correct and both were useless: they understated a + two-and-a-half-day archive by roughly 275x, because the last restart was 12 + minutes earlier. A visitor cannot tell a permanently-young instance from a new + one. Prefer durable values — archived event count, elapsed since the run + began, `complete` repository count — and reserve process-local figures for + `/status`, where a reader is looking at *this process* rather than the + archive. `0 listening` is fine and honest: serving is gated until steady + state. + + This is the batch-boundary restart defect surfacing publicly rather than a + copy mistake (`gotchas.md`, `HttpConnectionClosing`). Worth fixing in the copy + regardless, since a durable counter is the right thing to show even once the + process stops dying. ## Presentation guardrails