Concept paper · dev-companion · draft 2

A record of reads for every source

What the status page must keep about its own reads, for the reader who asks since when a source has failed. The pages as they stand, what readers asked, three options weighed, and the one this paper recommends.

Mara Lindqvist · for the status pages draft 2 · 2026-09-15

State: draft for discussionnot a decision
Date: 2026-09-15
Audience: The maintainers of the server, the writers of the status pages
Subject: The status page and the page of a source in dev-companion 1.4
Decision by: 2026-09-30, at the maintainers’ call

Summary

The status page says which sources answer, and the page of a source shows the read in flight and the two before it. Readers ask a question neither page can answer: since when, and how often. Twenty-four times in thirty days, and five of eight readers in a test.

Recommendation: option A. The server keeps the last thirty reads of every source in one file, the page of the source shows them as a list under the read in flight, the status row carries the last five as marks, and the terminal prints the count. Six days in five packages. It stays a record of this machine’s own reads, which is what the pages already promise, and not a history of a service, which they refuse on purpose.

1 Purpose

One question, and the evidence behind it. The pages report the moment. Readers ask about the days before it. This paper says what the server must keep so the pages can answer, and what it must not become on the way.

1.1 What this paper decides

If the server keeps a record of its own reads, how long that record is, and where it shows. Three options stand in part 6, and part 8 asks the maintainers for one of them. Everything before that is what the decision rests on.

The path through the paper

Part 2 is the pages as they stand. Part 3 is what readers asked and what a test showed. Part 4 names the findings. Part 5 is the proposal, part 6 the options against it, part 7 the cost. Part 8 is the question. A reader with ten minutes reads the summary, part 6 and part 8.

1.2 What it leaves out

A history of the source itself. If docs.typo3.org was up is a question about a service, and the status page refuses it on purpose. This paper keeps that refusal; see 2.3.
Alerts. A read that stops tells nobody. A record makes that visible after the fact, which is a different thing from a message at the time, and a paper of its own.
The other four sources. The two on this machine and the two that ship with the server never fail a read. The record applies to them and stays empty of anything but "read".

2 Where it stands

The two pages, as a reader sees them in 1.4, read against each other. Then a table for each: what the page says, and what a reader asks of it.

2.1 The two pages

The status page has six rows, one per source: the state now, when the checker last asked, and the way into the source. The page behind a row shows the read in flight, the overview, and "Earlier reads": the last read that ended and the one that stopped. It keeps those two and no more.

The status page

The page of a source

The page of the source docs.typo3.org at its lower half. An overview, then two folded rows under Earlier reads, then a note: this is a source, not a service. — The page keeps the last read that ended and the one that stopped, and nothing before them.

2.2 What the row says

The row says	The reader asks	Answered
The state of the source, as a badge	Is it answering right now?	yes
When the checker last asked	Did the check run?	yes
Nothing about the check before this one	Since when has it been like this?	no
Nothing about how often	Is it always this slow?	no

2.3 What the page keeps

The page shows	How far back	Enough for
The read in flight, stop by stop	now	a reader who waits for it
The last read that ended	six hours	a reader who wants the last verdict
The read that stopped	a day	a reader who asks what went wrong once
Nothing before those	—	nobody who asks how often, or since when

2.4 What the pages say on purpose

The status page ends on a note, and the note is a decision. This paper does not argue with it. It asks if a record of the server’s own reads is the history the note refuses, and finds it is not: the note is about the source, seen from anywhere, and the record is about this machine, and only that.

There is no incident history, because there is no service. Nothing is hosted for you to depend on. What would be an outage elsewhere is a degraded answer here, and the answer says so at the moment it is given.

The status page · the note at its foot dev-companion 1.4

3 What readers asked

Two kinds of evidence. The questions that arrived on their own, over thirty days, and a test that put eight readers in front of the pages with four tasks.

3.1 The questions that arrived

Every question about the status pages in chat and in the issue tracker between 2026-08-15 and 2026-09-14, grouped by what it asks. The list itself is A.3.

Question, as it arrived	Times	Where	The page can answer it
Since when is releases.typo3.org unreachable?	11	chat, the issue tracker	no
Is docs.typo3.org always this slow, or only today?	6	chat	no
Did the read run tonight?	4	the issue tracker	for the last read
How long has a full read taken lately?	3	chat	for the last read

3.2 A test with eight readers

Eight people who run the server for their own projects, each alone with the two pages and four tasks, on 2026-09-08 and 2026-09-09. The script is A.1. A task counts as done when the answer is right, and a guess that was right counts as a guess.

Task	Done	Median	What happened
T1 · Say if the last read of docs.typo3.org ended well	8 of 8	12 s	the page answers it
T2 · Find the read that stopped yesterday	7 of 8	31 s	one reader opened the wrong source
T3 · Say since when releases.typo3.org has been unreachable	3 of 8	2 min 40 s	five gave up; the three guessed from the two reads
T4 · Say how often docs.typo3.org was slow this week	0 of 8	—	nothing on the page holds a week

The two tasks the pages hold an answer for went well. The two that ask about the days before went badly, and in the same way: every reader opened the two earlier reads and looked under them for a third.

3.3 What they said

Two sentences from the interviews after the tasks, each said in some form by more than one reader.

I can see that it stopped yesterday. I cannot see if yesterday was the first time.

Reader 3 · runs the server for two agencies

The note says it is not a service, and that is fine. I still want to know what my own machine did last week.

Reader 7 · runs it on a laptop

4 Findings

What the evidence says, in three groups: what stands in the way of the goal, what costs the reader, and what already does its job and must stay. Every finding in one table first, each row a jump to its entry, and the work they ask for in a second.

	Entry	Kind	Origin
F1.1	Nothing on either page says since when	gap	from the questions and from T3
F1.2	Nothing holds a week, so nobody can say how often	gap	from T4
F2.1	A reader who found the answer read it off the wrong page	costs	from T3
F2.2	The row cannot carry a record, and the reader looks there first	costs	from the test, all four tasks
F3.1	Readers find the read that stopped	keep	from T2
F3.2	The pages say what they are not, and the readers read it	keep	from the interviews

To do

	To do	Kind
W1.1	Keep the reads before the last two, and show them where the reader asks: on the page of the source.	gap
W1.2	Thirty reads, which is five days at the schedule, and a count of the verdicts over them.	gap
W2.1	The record on the page of the source, so the answer stands where the question starts.	costs
W2.2	Five marks at the end of the row: a glance, and the page for the rest.	costs

A gap

F1.1

Nothing on either page says since when

gap from the questions and from T3

Eleven of the twenty-four questions ask since when a source has failed, and it is the one question both pages cannot answer. The row says what the source does now. The page of the source keeps two reads. A source that stopped four days ago looks like one that stopped this morning.

W1.1Keep the reads before the last two, and show them where the reader asks: on the page of the source.

F1.2

Nothing holds a week, so nobody can say how often

gap from T4

Every reader failed T4, and every one of them tried the same thing: they opened the two reads and looked for a third. A count over thirty reads answers "how often" for the week the question is about.

W1.2Thirty reads, which is five days at the schedule, and a count of the verdicts over them.

Costs the reader

F2.1

A reader who found the answer read it off the wrong page

costs from T3

The three readers who answered T3 guessed the day from the two reads on the page and gave the guess as the answer. A guess a page invites is a wrong answer the page gave.

W2.1The record on the page of the source, so the answer stands where the question starts.

F2.2

The row cannot carry a record, and the reader looks there first

costs from the test, all four tasks

Every reader started on the status page and read the row before they opened the source. A row has room for a glance and no more. Five marks say "this happened before" and not when, and the page under the row says the rest.

W2.2Five marks at the end of the row: a glance, and the page for the rest.

Works as it stands

F3.1

Readers find the read that stopped

keep from T2

Seven of eight readers found it, in half a minute. The fold under "Earlier reads" is the right shape for one read, and the record keeps it.

F3.2

The pages say what they are not, and the readers read it

keep from the interviews

Six of eight readers named the note at the foot of the status page unasked. "It is not a service" reached them. So a record of the server’s own reads does not read as a promise about the source, as long as the page says so.

5 The proposal

The server keeps a record of its own reads, and every surface that shows the reads reads that record. Three surfaces, one file, and a name for what it is.

5.1 A record, not a history

It is about this machine. A read the server made from here, with the verdict it reached here. Nothing about the source seen from anywhere else, and no claim that it was up or down.
It is short. Thirty reads, which is five days at the schedule of six hours. The thirty-first drops the first. A year of reads is a history, and part 6 says why that is the wrong thing.
It says so. The note at the foot of the status page grows one sentence, and the record’s own heading names it: "Reads from this machine".

5.2 What the record holds

One entry per read. Four fields, each the answer to a question from 3.1.

Field	Holds	Why
started	when the read began, on this machine’s clock	the answer to since when
verdict	read, slow or stopped	the word the row already uses
took	how long, or at which stop it ended	the answer to how long lately
pages	what the read put in the index	a read that ended well but read nothing is a stopped one

The record is one file per source, beside the index the reads fill. It lives where the cache lives, so a reinstall keeps it and a cleared cache takes it.

typo3-dev-companion/the server’s cache, under ~/.cache
- docs/one directory per source
  - index/what the last read put there
  - reads.jsonthe record: the last thirty reads, oldest dropped first
- releases/
  - index/
  - reads.json

5.3 Where it shows

Three places, from a glance to a sentence. The page of the source carries the record in full, because that is where the question starts (F2.1).

Three boxes side by side. The row on the status page: the source name and five small coloured marks. The page of the source, drawn in the accent: four rows, each a mark, a date, a verdict and a duration. The terminal: a dark box with one command and its two-line answer. Under them, one sentence: a record of the server’s own reads, not a history of a service. — One record, three places it shows. The page of the source carries all thirty reads; the row carries five as marks; the terminal counts them.

On the page of the source the record stands under the read in flight and above the overview, where "Earlier reads" stands today. The two folds the page keeps become the first two rows. Nothing above them moves.

The read in flight stays first. A reader who came to wait for it waits there.
"Reads from this machine" replaces "Earlier reads": thirty rows, newest first. Each row is a mark, a time, a verdict and a duration. A stopped read keeps its fold, and the fold keeps what the stop wrote.
The overview moves below the record. It changes once a year; the record changes four times a day.
The note at the foot grows one sentence: what the record is a record of.

5.4 The row on the status page

Five marks at the end of the row, oldest first, one per read. A mark is a colour and a word, as every result in the system is, so the row reads without sight. A row of five green marks says "as always". A row that turns red at the third says "since the day before yesterday", with no number in it.

Source	State	Last five reads
knowledge	answering	readreadreadreadread
docs.typo3.org	slow · 2.4 s	readreadslowreadslow
releases.typo3.org	unreachable	readstoppedstoppedstoppedstopped

5.5 In the terminal

For the reader who asks from a shell and never opens a page: one line per source, the count over the record and when the last read ended.

bash

$ dev-companion status docs
docs.typo3.org · 30 reads · 27 read · 2 slow · 1 stopped · last 06:00 today

5.6 The setting

One value decides how long the record is. It counts reads and not days, because the schedule is a setting too; part 7 names the risk.

reads.keep

type: integer
default: 30
Set in: settings.yaml, per installation
Applies to: every source

How many reads of a source the server keeps. The thirty-first drops the first. Thirty is five days at the default schedule of six hours. A value of zero keeps the two reads the page keeps today, which is the state before this paper.

5.7 What the note says

The note at the foot of the status page grows one sentence, so the record never reads as the history the note refuses. The four lines before it stay as they are.

Resources/Private/Templates/Status.html

   There is no incident history, because there is no service.   …+  What the page of a source keeps is a record of the reads this+  server made from this machine, and nothing about the source+  seen from anywhere else.

6 Options weighed

Three ways to answer the two questions, against what the findings ask. The recommendation is the first column. The third is the fallback if six days is too many.

6.1 The three, in short

Option A

The record on the page of the source

Thirty reads in a list under the read in flight. Five marks in the row, one line in the terminal. A record of this machine, on the page that already says what it is.

6 days · recommended

Option B

A page of its own, with a chart

A year of reads, drawn. It answers every question, and it reads as a service somebody watched, which the pages refuse on purpose.

14 days

Option C

Marks in the row only

Five marks at the end of the row and nothing else. It answers since when for five reads and how often for none.

2 days · the fallback

6.2 Side by side

Asks	A · The record on the page of the source	B · A page of its own, with a chart	C · Marks in the row only
Answers since when	yes	yes	for five reads
Answers how often	for thirty reads	for a year	no
Reads with no sight	a list	a chart needs a table beside it	a colour and a name
New surface	none	one page, one chart	none
Stays a record, not a history	thirty reads	a year is a history	five reads
Cost	6 days	14 days	2 days

6.3 Why not the chart

Option B answers every question and costs twice as much. It fails on the one thing the pages refuse: a year of reads on a page of its own, with a chart, is an incident history with another name. A reader who sees it reads a service.

A chart of a year is a promise

The pages promise nothing about the source. A page that draws a year of its verdicts promises that somebody watched. Option A keeps five days, on the page that already says what it is.

7 What it costs

Five packages, six days, one order. And what can go wrong on the way.

7.1 Work packages

Package	What it does	Cost	Needs
W1	The server keeps the last thirty reads of a source in one file beside its cache	2 days	—
W2	The page of a source shows the record under the read in flight	2 days	W1
W3	The status row carries the last five reads as marks	1 day	W1
W4	dev-companion status <source> prints the record as one line	½ day	W1
W5	The manual says what the record is and what it is not	½ day	W2, W3

7.2 The order

Decide

The maintainers answer the question in part 8 by 2026-09-30. Nothing below starts before that.

Keep the record

W1. One file per source, thirty reads, oldest dropped first. The file is the contract; every surface below reads it. Merged behind a flag, on by default in 1.5.

Show it on the page of the source

W2. Under the read in flight, above the overview. The two reads the page keeps today become the first two rows of the record.

Marks in the row, the line in the terminal

W3 and W4, in either order. Both read the same file.

Say what it is

W5. The manual and the note on the status page say what it is: reads from this machine, not a history.

7.3 The dates

The same order on the calendar, and where it stands today.

2026-09-15

Draft 2 to the maintainers

This paper, with the test and the options in it.

2026-09-30

DecisionNow

The maintainers answer the question in part 8. Nothing below starts before that.

Sprint 1 · 2026-10-05 to 10-16

The record, kept

One file per source, thirty reads. Merged behind a flag.

W1

The server keeps the last thirty reads

Sprint 2 · 2026-10-19 to 10-30

The record, shown

Every surface reads the same file.

W2

The page of a source shows the record

W3

Five marks in the status row

W4

One line in the terminal

2026-11-10

Release 1.5

W5 with it: the manual, and the note at the foot of the status page.

7.4 Risks

R1 · A record on a laptop that sleeps is a record with holes

A machine that was off made no reads. The record says nothing for that time, and a reader can read the gap as a failure. The list marks a gap of more than twelve hours as its own row, with the words: no read, the server was not running.

R2 · Thirty reads of a source read every hour is one day

The schedule is a setting. A reader who reads every hour keeps a day and not five. The record counts reads and not days on purpose, and the manual says which it is.

8 Decision

Decision

Does the server keep a record of its own reads, and show it?

Until the maintainers answer, this paper is a draft and the pages stay as they are. The three answers are part 6 in short; the cost of each is part 7.

A

The record on the page of the source recommended

Thirty reads, on the page of the source; five marks in the row; one line in the terminal. Six days.

B

A page of its own, with a chart

A year of reads, drawn. It is a history, and fourteen days.

C

Marks in the row only

It answers since when for five reads and how often for none. Two days.

Decision by the maintainers · due 2026-09-30

8.1 Open questions

Does the record survive a reinstall? It lives beside the cache, which a reinstall keeps. The paper assumes yes and W1 confirms it.
Does the row carry five marks on a phone? The table drops the marks where it drops the "last checked" column. To confirm in W3.
Is thirty the number? Five days at the default schedule. The maintainers can set another before W1; the file format does not care.

8.2 Sources

The status page and the page of a source in dev-companion 1.4, as shipped.
The chat and the issue tracker, 2026-08-15 to 2026-09-14; the list is A.3.
The test of 2026-09-08 and 2026-09-09, eight readers; the script is A.1.
The manual, “What a source is” , for the sentence the record must not contradict.

9 Appendix

A.1 · The test, as it ran

Eight readers, each alone, each with the two pages open in a browser and a timer beside them. Four tasks, read out one at a time. A task ends when the reader gives an answer or gives up. The median is over the readers who finished.

text

T1  Say if the last read of docs.typo3.org ended well.
T2  Find the read that stopped yesterday.
T3  Say since when releases.typo3.org has been unreachable.
T4  Say how often docs.typo3.org was slow this week.

A.2 · The record, as a file

~/.cache/typo3-dev-companion/docs/reads.json

json

[
  { "started": "2026-09-15T06:00:11Z", "verdict": "read", "took": 182, "pages": 18412 },
  { "started": "2026-09-14T06:12:04Z", "verdict": "stopped", "took": 131, "at": 2 },
  { "started": "2026-09-14T00:00:09Z", "verdict": "read", "took": 178, "pages": 18410 }
]

A.3 · The questions, in full

Twenty-four questions from chat and the issue tracker between 2026-08-15 and 2026-09-14, each with the source it names. The table in 3.1 groups them by what they ask. The list stays out of this paper: it names people.