Write the operator guide - #124
Merged
Merged
Conversation
The page somebody who has never seen this board reads before running anything from it. It walks getting the runner, a first run with its exact output, a run over a tree with no experiments, the listing, and what a refusal looks like, and it carries the three questions somebody decides in half a minute on: that the runner changes nothing, sends nothing anywhere, and needs no privileges. Each of the three is written as a limit with the test or the record behind it rather than as an assurance. The exit codes are explained by pointing at record 0011 rather than by restating it, and what the page adds is the half a record cannot show: which invocation produces each code, with the command and the output. It also says that the runner returns three of the four the record fixes and where the fourth one's producer is. Two absences are stated rather than papered over. There is nothing to download, so nothing here walks a download or a checksum, and whether anything is ever published is not decided. There is no licence file, so the page names its absence where a reader would otherwise look for permission to reuse what they find. The compatibility position lands here because it has nowhere else to live yet. It points at record 0013 for what happens to records already on the default branch when the format changes, and says that a change is announced by the record that decides it, there being no changelog in the tree. Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
This was referenced Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The operator guide,
docs/operator-guide.md, which is issue #42, and the twoclauses that were waiting on it: the exit-code pointer #52 stays open on, and
the compatibility position #64 stays open on. Part of #44 lands here as well,
in the section that states the compatibility position, since #44 allows it to
live in the changelog or in this guide and there is no changelog.
The means is Markdown prose under
docs/, which is what every other documenton this board is made of. It fits because the artefact is read by a person
rather than executed, and because the checks that already exist over this
repository's prose, its named paths and its formatting reach it without a
parallel apparatus: the run below is the same gate every other document here
passes.
What it says
The three questions somebody decides on in half a minute are near the top, and
each one is written as a limit with the test or the record behind it. The
runner changes nothing in the tree it reads, and
TestWalkWritesNothingisnamed with the bound on what it covers. It sends nothing anywhere, pointing at
docs/privacy.mdrather than restating the claim. It needs no privileges andno display, pointing at record 0007.
The exit codes are explained by pointing at
docs/decisions/0011-the-exit-codes.mdand not by restating it. What the pageadds is the half that record cannot show: which invocation produces each code,
with the command and its output, and that
labreturns three of the four codesthe record fixes while the fourth is declared where its producer is under
internal/hardware.The compatibility position points at
docs/decisions/0013-how-the-record-format-changes.mdfor what happens to records already on the default branch when the format
changes, and states that a change is announced by the record that decides it,
there being no changelog in the tree.
What it does not say, deliberately
There is nothing to download, so nothing on the page walks a download or a
checksum. That is stated in the section where a reader looks for it rather than
being left as a gap, together with the fact that whether anything is ever
published is not decided.
There is no licence file, so the page names its absence where a reader would
otherwise look for permission to reuse what they find.
Both absences are why #42 is not closed by this pull request. Its done-condition
asks for a walk through download and checksum, and neither exists to be walked.
The evidence
Every output quoted in the guide was produced by running the command against a
fresh clone at
bbfab50, built from that clone, rather than against a workingtree.
go build,go vetandgofmt -lprinted nothing, which is the passingresult for all three. The lines between the suite command and its results are
the per-package output and nothing else is cut.
The two checks this change is most likely to break, run on their own so the
report each prints is readable:
The licence leg reports that it was not asked, which is its ordinary state
while that question is open, and the rest of its message names what asking
would cost. That sentence is cut after the first line and nothing else is.
The path leg is the one that matters here: it read 30 documents, one more than
before this change, and every path the new page names resolves in this tree.
Reading
This change has had no second reader, and the evidence above stands in place of
one rather than alongside it.