Docs: a callout is recognised by its shape, not by one exact phrase - #48
Merged
Merged
Conversation
The README's two load-bearing callouts were renamed to **Important** and **See** in 1f17347, and TestTheKnownLoadBearingLinesAreMarkedInPlace went red: it grepped for the literal marker "load-bearing documentation". What §11 asks of one of these lines is that it stand in front of the reader visibly and that the decision behind it be reachable. Both are still true of the renamed callouts, and both are things the suite can decide. The exact wording of the lead-in is not, so calloutsIn now recognises a callout two ways: the class's own marker, or a bold blockquote lead-in naming an issue in this repository. An editing pass over a document's prose is no longer a test failure; deleting the callout, or the ticket in it, still is. Also fixes four typos the suite cannot see, in the same README edit: "an dbuilds", "doesn't pushe", the "Does obsync fi your use case?" heading, and trailing whitespace on five wrapped lines. Co-Authored-By: Claude Opus 5 <[email protected]>
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
1 participant
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.
mainis red: the README rename in 1f17347 turned the two load-bearing callouts into**Important**and**See**, andTestTheKnownLoadBearingLinesAreMarkedInPlacegrepped for the literal markerload-bearing documentation.The test change
calloutsInnow recognises a callout two ways — the class's own marker, or a bold blockquote lead-in that names an issue in this repository. The two properties the suite can actually decide are that the line is visibly called out and that the decision behind it is reachable; both hold for the renamed callouts, whichever word they open with. The exact wording of the lead-in is prose, and checking it made an editing pass a test failure.It is eased, not disabled. Verified on a scratch copy: stripping the
#16link from the Headless Sync callout, or deleting the never-list callout, still fails the test.The README
Four typos from the same edit that no test can see:
an dbuilds,doesn't pushe, theDoes obsync fi your use case?heading, and trailing whitespace on five wrapped lines. No prose was otherwise rewritten.Verification
go test -race ./...,go vet ./...andgofmt -lall clean, run ingolang:1.25-bookwormas a non-root user.Not addressed here
The same commit deleted the body of the Headless Sync warning — the conflict-copies explanation, the pointer to
docs/operations.md#when-something-else-is-writing-the-vault, and "Never cut this warning" — along with the "Nothing is published yet" and "Status" sections. No test covered that body, so this PR neither restores it nor hides its absence; the warning is now its headline sentence alone.🤖 Generated with Claude Code