Docs: a hero and badges at the top of the README, and the coverage number behind one of them - #49
Merged
Merged
Conversation
The number is measured with -coverpkg=./..., because every test obsync has lives in the root package and drives the internal packages through it. By default Go credits a package's coverage only to that package's own tests, so internal/vault, internal/git and the rest would each report 0% and the badge would say the suite touches almost nothing. It is published as shields.io endpoint JSON on an orphan `badges` branch rather than as a rendered SVG. GitHub proxies README images through a cache that has no idea the file changed, so a committed SVG would show whatever percentage was true the first time somebody looked. The branch is force-pushed to one commit every time: it is a value rather than a history, and nothing needs last week's number. Push to main only. A fork's token cannot write to this repository, so a coverage job that ran on a pull request could only ever be a red cross on somebody else's work. Co-Authored-By: Claude Opus 5 <[email protected]>
The hero is a schematic of the seam obsync sits in: the vault above, origin/main below, and two arcs between them carrying dashes in the direction each one moves work — push out of the vault's right edge, pull back into its left. The wordmark's rule says the same thing in miniature: violet up to where `ob` ends, rust from there, with a tick on the join. One file rather than a light one and a dark one. It carries the dark palette as its base and swaps to paper under prefers-color-scheme: light, so there is no second file to keep in step. Nothing external is referenced, because nothing external loads inside the <img> GitHub renders it in, and the motion respects prefers-reduced-motion. The row is CI, coverage, Go version, latest release, the image and the licence. The coverage badge reads `resource not found` until this lands on main and the job it reads from creates the branch. 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
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.
Adds a hero image and a badge row to the top of the README, and the CI job that
produces the one number the README could not otherwise show.
The hero
docs/assets/hero.svgis a schematic of the seam obsync sits in: the vaultabove,
origin/mainbelow, and two arcs between them carrying dashes in thedirection each one moves work — push out of the vault's right edge, pull back
into its left. The wordmark's rule says the same thing in miniature: violet up
to where
obends, rust from there, with a tick on the join.One file rather than a light one and a dark one. It carries the dark palette as
its base and swaps to paper under
prefers-color-scheme: light, so there is nosecond file to keep in step. Nothing external is referenced, because nothing
external loads inside the
<img>GitHub renders it in, and the motion respectsprefers-reduced-motion.The tradeoff of the single file: that query follows the reader's OS rather than
GitHub's own theme toggle, so a reader whose two settings disagree gets the
plate that does not match their page. It still looks deliberate; it is just not
matched. The
<picture>route tracks the toggle exactly, at the cost of asecond file to keep in step.
The badges
CI, coverage, Go version, latest release, the image and the licence. All
shields, one
labelColor.The coverage number
A
coveragejob, push-to-main only, withcontents: writeat job level ratherthan workflow level, which is where §12 says a write scope goes.
-coverpkg=./...is load-bearing. Every test obsync has lives in the rootpackage and drives the internal packages through it, and by default Go credits
a package's coverage only to that package's own tests — so
internal/vault,internal/gitand the rest would each report 0% and the badge would say thesuite touches almost nothing.
The number is published as shields.io endpoint JSON on an orphan
badgesbranch, force-pushed to one commit every time. A rendered SVG committed to the
repository would have been cached by GitHub's image proxy and frozen at
whatever percentage was true the first time somebody looked.
Two things worth knowing
resource not foundon this PR. The job thatcreates the
badgesbranch runs on pushes tomainonly, so the branch doesnot exist until this merges. It resolves itself on the first run.
credential_test.goandrelease_test.gofailing for container reasons rather than real ones (nobash, nogit-http-backendin the alpine image used to run them off a hostwith no Go). CI's number should land somewhat higher.
Checks
Go is not on this host's PATH, so the doc- and CI-policing tests were run in
golang:1.25-alpine.TestEveryRelativeLinkInTheDocSetResolves,TestTheDocumentationSetIsTheSevenPiecesTheDesignNames,TestCIReadsTheGitFloorFromThatOneFileRatherThanRepeatingIt,TestCIReadsTheBaseImageFromTheDockerfileRatherThanRepeatingItandTestCIRunsEverySeam2TestItsPatternCanSelectall pass.🤖 Generated with Claude Code