docs: correct coverage figures, stale examples, and broken links - #63
Merged
Conversation
Coverage numbers in the root README were stale in both directions and three packages had none at all. Regenerated from a real unit+integration run: server 77.1 -> 97.0, grpc 71.2 -> 82.0, db 76.7 -> 83.5, ssh 78.2 -> 85.6, concurrent 95.1 -> 100.0, and argo (94.8), retry (100.0) and base32 (100.0) gained the figures they never had. The README also pointed readers at output/coverage-all.html, which no task produces, and claimed a methodology that did not match the task it named. examples/otel was entirely pre-v3: a /v2 import path, struct-literal configs, and a link to otel/examples/example.go, a directory that does not exist. The example itself built its configs with struct literals, which silently skips the default logger provider NewConfig installs — so it was teaching a pattern that loses logging. Converted to functional options and verified the program still produces its documented output. docker/README linked the deleted logging package. Three READMEs linked a CONTRIBUTING.md that was never written; rather than delete the promise, write the file, since the contribution workflow it describes already existed scattered across README and INSTRUCTION. compress and ssh example READMEs gave run instructions from directories that do not exist and omitted the example build tag, so they could not have worked. Backlog: separate what is resolved from what is open, with pointers to where each fix landed. Two entries were verified still present rather than assumed fixed — the ssh accept-loop stopCh race and wg.Add race remain open and are now recorded with line numbers.
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.
Coverage figures
Stale in both directions, and three packages had none. Regenerated from a real unit+integration run (
-tags=integration, Docker-backed testcontainers):The README also told readers to open
output/coverage-all.html— no task produces that file — and described a methodology that did not match the task it named. Now: figures come fromtask test:integration→output/coverage-integration.html;task test:completeadditionally runs argo (needs k8s) →output/coverage-complete.html.examples/otel was entirely pre-v3
/v2import path, struct-literal configs throughout, and a link tootel/examples/example.go— a directory that does not exist.The example program itself used
&otel.Config{...}. That still compiles, butloggerProviderSetis unexported, so a struct literal silently skips the default zerolog logger provider thatNewConfiginstalls. The example was teaching a pattern that quietly loses logging. Converted to functional options; verified the program still prints its documented output (the no-op example needed an explicitWithoutLogging()to stay all-false, which is exactly the trap worth showing).Broken links and unrunnable instructions
docker/README.mdlinked the deletedloggingpackage and said "OpenTelemetry v2".CONTRIBUTING.mdthat was never written. Rather than delete the promise, wrote the file — the workflow it describes already existed, scattered across README and INSTRUCTION.examples/grpc/README.mdlinked../README.md(nonexistentexamples/README.md).examples/compressandexamples/sshgave run instructions from<pkg>/examples/directories that do not exist, and omitted theexamplebuild tag — so they could not have worked. Both verified withgo build -tags=example.Full markdown link scan now clean except two links inside historical
docs/plans/records, deliberately left as point-in-time documents.Backlog hygiene
Split resolved from open, each with a pointer to where the fix landed. Notably, two entries were verified still present rather than assumed fixed:
ssh's accept-loop readst.stopChunlocked at three points whileStartreassigns it undert.mu, andt.wg.AddafterAcceptstill racesClose'swg.Wait. Only the busy-spin half of that item was ever fixed. Recorded with line numbers; left open deliberately as a v3.x item.Two backlog items are now closed as decisions rather than defects — docker's
Inspect/GetStatsescape hatches (ADR 0004) and the server/grpc lifecycle divergence (ADR 0005).Verification
task ci:checkgreen (0 lint issues),go vet -tags='example integration argo' ./...clean,CLAUDE.md==AGENTS.mdparity confirmed.