Skip to content

Docs: a hero and badges at the top of the README, and the coverage number behind one of them - #49

Merged
andyroberts2 merged 2 commits into
mainfrom
docs/readme-hero-and-badges
Aug 27, 2026
Merged

Docs: a hero and badges at the top of the README, and the coverage number behind one of them#49
andyroberts2 merged 2 commits into
mainfrom
docs/readme-hero-and-badges

Conversation

@andyroberts2

Copy link
Copy Markdown
Owner

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.svg 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 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 a
second 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 coverage job, push-to-main only, with contents: write at job level rather
than workflow level, which is where §12 says a write scope goes.

-coverpkg=./... is load-bearing. Every test obsync has lives in the root
package 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/git and the rest would each report 0% and the badge would say the
suite touches almost nothing.

The number is published as shields.io endpoint JSON on an orphan badges
branch, 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

  • The coverage badge reads resource not found on this PR. The job that
    creates the badges branch runs on pushes to main only, so the branch does
    not exist until this merges. It resolves itself on the first run.
  • A local run measured 78.7%, and that was with credential_test.go and
    release_test.go failing for container reasons rather than real ones (no
    bash, no git-http-backend in the alpine image used to run them off a host
    with 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,
TestCIReadsTheBaseImageFromTheDockerfileRatherThanRepeatingIt and
TestCIRunsEverySeam2TestItsPatternCanSelect all pass.

🤖 Generated with Claude Code

andyroberts2 and others added 2 commits August 27, 2026 16:55
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]>
@andyroberts2
andyroberts2 merged commit deefa51 into main Aug 27, 2026
5 checks passed
@andyroberts2
andyroberts2 deleted the docs/readme-hero-and-badges branch August 27, 2026 15:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant