Walk the download and the checksum in the operator guide - #211
Merged
Merged
Conversation
The guide said there was nothing to download, that this board publishes no binary and no checksum file, and that whether anything is ever published was not decided. Two of those three sentences stopped being true when record 0021 answered the question and the release workflow landed: the workflow fixes the asset names, the checksum file and its format, so the walk this issue asks for no longer has to guess at the thing it describes. What is added is a download route and a checksum check, with the command written out for each platform, because a checksum nobody knows how to check is decoration. Linux and macOS get the two spellings of the same tool with --ignore-missing, which is what lets a reader check the two files they downloaded against a checksum file covering eight. Windows gets Get-FileHash with the line to compare it against, and certutil beside it, because neither shell there has a --check equivalent and the comparison is the reader's to make. The failure it prevents is an operator holding a downloaded binary with no way to tell whether the bytes arrived as they left, which is the state this page left them in while telling them there was nothing to download. Two things it does not do. It does not restate the signature verification: the release notes carry those commands and where the keys come from, and a second copy in this tree would drift against the one every release publishes. And it makes no claim that a release exists - the page tells a reader to open the releases page and says that an empty one means the checkout route is the only one available, so the sentence does not go stale on the day the first release is cut. Refs #42 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
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.
Closes #42.
What was wrong
docs/operator-guide.mdopened its "Getting it" section with three sentences,and two of them had stopped being true.
Whether anything is ever published is decided:
And the reason the download walk could not be written has ended. The last thing
recorded on #42 said a walk written before the artefact names existed would name
files by guessing them. Those names are fixed in the tree now:
So the walk is written against what that file produces rather than against a
guess, and every asset name in the new section comes from those lines.
What this changes
One file.
docs/operator-guide.mdgains a download route, a per-platformchecksum check and a pointer to where the signature is verified, and keeps the
checkout route it already had as the one that always works.
The per-platform half is what the issue asks for in as many words - "with the
command written out for each platform, because a checksum nobody knows how to
check is decoration". Linux and macOS get the two spellings of the same tool
with
--ignore-missing, which is what lets a reader check the two or threefiles they actually downloaded against a checksum file covering eight. Windows
gets
Get-FileHashwith theSelect-Stringline to compare it against, andcertutilbeside it, because neither shell there has a--checkequivalent andthe comparison is the reader's to make by eye.
What it deliberately does not do
It does not restate the signature verification.
docs/release-notes-preamble.mdcarries those commands and where the keys come from, and every release is
published with that text in its notes. A second copy here would be
restated-not-referencedagainst the one a downloader actually holds, so theguide points at it and adds the one sentence a reader needs before following it:
do not take the key from the release.
It makes no claim that a release exists, and none has been cut:
The page tells a reader to open the releases page and says that an empty one
means the checkout route is the only one available to them. That sentence is
true today and stays true on the day the first release is cut, which a sentence
asserting either state would not.
The means
Markdown prose in
docs/, which is the means every other operator-facingdocument on this board already uses and the one the prose rules and the paths
leg of the invariants scan can read. Nothing here needs a mechanism that prose
cannot carry: what the section asserts about the release is checkable against
.github/workflows/release.yml, which is quoted above rather than paraphrased,and the commands it hands the reader are run on their machine rather than by
anything here.
The gate
Run at the head of this branch,
2edacce:The paths leg of that last run is the one that matters for a change of this
shape: it resolves every repository-relative path a document under
docs/namesand refuses one that is not in the tree.
docs/release-notes-preamble.mdisnamed in prose and resolves. The release asset names are bare words with no
leading directory segment, which that reading deliberately does not treat as
paths, so nothing here asks it to resolve a file that only exists inside a
published release.
No second reader
This change has had no reader other than whoever wrote it. The evidence above
stands in place of one: the sentences it replaces are quoted from the default
branch, every asset name it introduces is quoted from the workflow that produces
it, and the two negative claims - no release, no tag - are the output of the
commands beside them rather than an assertion.