Skip to content

docs: correct coverage figures, stale examples, and broken links - #63

Merged
jasoet merged 1 commit into
nextfrom
docs/v3-accuracy-sweep
Aug 17, 2026
Merged

docs: correct coverage figures, stale examples, and broken links#63
jasoet merged 1 commit into
nextfrom
docs/v3-accuracy-sweep

Conversation

@jasoet

@jasoet jasoet commented Aug 17, 2026

Copy link
Copy Markdown
Owner

Coverage figures

Stale in both directions, and three packages had none. Regenerated from a real unit+integration run (-tags=integration, Docker-backed testcontainers):

package README said actual
server 77.1% 97.0%
grpc 71.2% 82.0%
ssh 78.2% 85.6%
db 76.7% 83.5%
concurrent 95.1% 100.0%
otel 84.8% 89.5%
compress 82.4% 85.3%
temporal 81.2% 84.5%
docker 83.1% 84.1%
config 97.6% 96.4%
rest 92.9% 93.0%
argo missing 94.8%
retry missing 100.0%
base32 missing 100.0%

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 from task test:integrationoutput/coverage-integration.html; task test:complete additionally runs argo (needs k8s) → output/coverage-complete.html.

examples/otel was entirely pre-v3

/v2 import path, struct-literal configs throughout, and a link to otel/examples/example.go — a directory that does not exist.

The example program itself used &otel.Config{...}. That still compiles, but loggerProviderSet is unexported, so a struct literal silently skips the default zerolog logger provider that NewConfig installs. 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 explicit WithoutLogging() to stay all-false, which is exactly the trap worth showing).

Broken links and unrunnable instructions

  • docker/README.md linked the deleted logging package and said "OpenTelemetry v2".
  • Three READMEs linked a CONTRIBUTING.md that 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.md linked ../README.md (nonexistent examples/README.md).
  • examples/compress and examples/ssh gave run instructions from <pkg>/examples/ directories that do not exist, and omitted the example build tag — so they could not have worked. Both verified with go 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 reads t.stopCh unlocked at three points while Start reassigns it under t.mu, and t.wg.Add after Accept still races Close's wg.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/GetStats escape hatches (ADR 0004) and the server/grpc lifecycle divergence (ADR 0005).

Verification

task ci:check green (0 lint issues), go vet -tags='example integration argo' ./... clean, CLAUDE.md == AGENTS.md parity confirmed.

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.
@jasoet
jasoet merged commit 143822b into next Aug 17, 2026
1 check passed
@jasoet
jasoet deleted the docs/v3-accuracy-sweep branch August 17, 2026 11:27
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