docs(examples): split cmd/quickstart into Quick Start + e2e variants#3
Merged
Conversation
README's Quick Start is a 45-line inline snippet; the runnable
program in cmd/quickstart is a 13-phase ~260-line end-to-end
walk-through. The two pieces drift independently — the README
was using outdated ceremony (panic instead of log.Fatal,
IIFE-wrapped defer Close, a 5-second WithTimeout that could
never fire in a happy-path run, a // Output: "..." comment
that's a godoc convention that doesn't apply to cmd/ binaries)
while the program had been refined to cover every exported
symbol in a single go run.
Split cmd/quickstart into two binaries so each piece has a
single, clear job:
cmd/quickstart (NEW 73-line minimum viable example)
Mirrors README's Quick Start 1:1. Single broker, single
publisher, single subscriber, single topic, one Publish,
one Receive. Synchronous Publish means the 200ms
WithTimeout demonstrably resets on the happy path
(select hits the Ch branch, never the ErrCh one).
`go run ./cmd/quickstart` prints:
Received: CPU over 90%!
cmd/quickstart-e2e (renamed, content unchanged)
The 13-phase end-to-end walk-through that previously
lived at cmd/quickstart/main.go. Same surface, same
phase numbering, same output. Only the trailing
"quickstart: ok" was renamed to "quickstart-e2e: ok"
to match the new binary name.
README's Quick Start is rewritten to be 1:1 with the new
simplified binary. It now points at cmd/quickstart-e2e for
the long-form walk-through instead of being a single
self-contained snippet.
cmd/quickstart/README.md is rewritten to describe the
minimal binary and point at cmd/quickstart-e2e/README.md
for the longer walk-through. cmd/quickstart-e2e/README.md
is the previous contents of cmd/quickstart/README.md
with internal references updated to the new path.
No library code changes; existing unit tests in pubsub/
remain the contract.
Verified:
go run ./cmd/quickstart Received: CPU over 90%!
go run ./cmd/quickstart-e2e quickstart-e2e: ok
go build ./... ok
go vet ./... clean
gofmt -l $(git ls-files) clean
go test -race -count=1 ./... 3.1s, green
Co-Authored-By: MiniMax-M3
The contents of [Unreleased] (the BREAKING rename of SubscriptionCapacityExceed → ErrSubscriptionCapacityExceeded, the hot-path alloc reductions, the persistent timer rework, the lazy ErrCh contract, the cmd/quickstart split, the lint pin to v2.12.2, etc.) are the v1.1.0 release notes. Promoting the section header to "## [v1.1.0] - 2026-06-13" so the diff link at the bottom can point at a real compare URL. No [Unreleased] stub is added — when the next change ships that needs a CHANGELOG entry, the section can come back. This matches the v1.0.0 entry above, which also has no forward-looking placeholder. Verified: go build ./... ok go vet ./... clean gofmt -l $(git ls-files) clean go test -race -count=1 ./... 3.1s, green Co-Authored-By: MiniMax-M3
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.
Why
README's Quick Start is a 45-line inline snippet, but the runnable
program in
cmd/quickstarthad been growing into a 13-phase~260-line end-to-end walk-through. The two pieces drift
independently:
IIFE-wrapped defer Close, a 5-second WithTimeout that could
never fire in a happy-path run, a
// Output: "..."commentthat's a godoc convention that doesn't apply to
cmd/binaries).
a single
go runand to demonstrate the documented APIcontract on its own.
The fix: give each piece a single, clear job.
What this PR does
New
cmd/quickstart(73 lines)A minimum viable example that mirrors README's Quick Start 1:1.
One broker, one publisher, one subscriber, one topic, one Publish,
one Receive. Synchronous Publish means the 200 ms
WithTimeoutdemonstrably resets on the happy path (the
selecthits theChbranch, never the
ErrChone).go run ./cmd/quickstart # → Received: CPU over 90%!cmd/quickstart-e2e(renamed, content unchanged)The 13-phase end-to-end walk-through that previously lived at
cmd/quickstart/main.go. Same surface, same phase numbering, sameoutput. Only the trailing
"quickstart: ok"was renamed to"quickstart-e2e: ok"to match the new binary name.go run ./cmd/quickstart-e2e # → 30-line transcript ending in "quickstart-e2e: ok"Docs
simplified binary.
cmd/quickstart/README.mdis rewritten to describe theminimal binary and point at
cmd/quickstart-e2e/README.mdforthe longer walk-through.
cmd/quickstart-e2e/README.mdis the previous contents ofcmd/quickstart/README.mdwith internal references updated tothe new path.
CHANGELOG.mdadds a### Changed (examples split)sectionsummarising the move.
What's not in this PR
pubsub/code is identical tomain. The existing unit tests inpubsub/remain the contract..github/workflows/test.ymlisthe contract; both
cmd/quickstart/main.goandcmd/quickstart-e2e/main.goalready passgofmt -l,go vet ./..., andgo test -race -count=1 ./....Verified locally