Skip to content

docs(go): rewrite the Go README for readability - #206

Open
lan17 wants to merge 1 commit into
mainfrom
claude/eager-allen-be73d7
Open

lan17 wants to merge 1 commit into
mainfrom
claude/eager-allen-be73d7

Conversation

@lan17

@lan17 lan17 commented Sep 22, 2026

Copy link
Copy Markdown
Owner

Rewrites go/README.md for a senior engineer skimming it: same facts, far less wall-of-text.

What changed

  • Structure now mirrors the TypeScript README's landing shape: one definition sentence, status line, links, the same nine capability bullets, Install, a complete runnable example whose comments carry the explanation, then verb-headed sections (Enable caching per request, Define use cases, Set and change policy, Connect Redis, Handle errors and deadlines, Choose value types and codecs, Export metrics and logs, Defaults, Advanced clock and executor hooks, Verify the port).
  • Reference facts moved into four tables: scope calls, error values, defaults, make targets.
  • Every fact from the previous text is retained. Protocol-internal terms (memo, frame, publication, leaf, budget, authority) are replaced or defined on first use; watermark and future buffer are defined where they first appear.
  • formal/source-audit.json (guide sha + heading lines for go/README.md) and the sourceAuditSha256 pin in formal/go-parity.json are refreshed. The guide's review scope text is unchanged because the rewrite keeps every topic it names.
Before After
Prose words 1,698 1,611
Sentences over 30 words 6 0
Paragraphs over 100 words 7 0
Longest paragraph 127 words 89 words
Sections / tables / code blocks 4 / 0 / 2 12 / 4 / 4

Verification

  • Both Go blocks compile (gofmt, go vet) against the module via a scratch module with a replace directive; the full program prints the expected Loading from source / Ada / Loading from source lines.
  • All 20 links resolve; docs-site anchors checked against the headings in docs/*.md.
  • make audit passes after the pin refresh.
  • Facts introduced by the rewrite were checked at source: go/v0.24.0 is the first Go tag and sits on the 0.24.0 release commit; pkg.go.dev and the reference site are live; sentinel errors, defaults, option semantics and invalid-runtime-policy consequences match go/api.go, go/cache.go, go/codec.go and go/policy.go.

Five lines still exceed 80 columns; each is a single link URL, as in the previous text.

Restructure go/README.md around the TypeScript README's landing shape:
one definition sentence, status line, capability bullets, install, a
complete runnable example, then verb-headed sections with tables for
scope calls, error values, defaults and make targets. Every fact from
the previous text is retained; protocol-internal terms are replaced or
defined on first use. Both Go blocks compile against the module.

Refresh the go/README.md guide entry in formal/source-audit.json and
the sourceAuditSha256 pin in formal/go-parity.json.
@lan17
lan17 force-pushed the claude/eager-allen-be73d7 branch from 40fb0e8 to 4dd247a Compare September 22, 2026 17:40

This branch has not been deployed

No deployments
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