Skip to content

docs(examples): split cmd/quickstart into Quick Start + e2e variants#3

Merged
F2077 merged 2 commits into
mainfrom
split/quickstart-e2e
Jun 13, 2026
Merged

docs(examples): split cmd/quickstart into Quick Start + e2e variants#3
F2077 merged 2 commits into
mainfrom
split/quickstart-e2e

Conversation

@F2077

@F2077 F2077 commented Jun 13, 2026

Copy link
Copy Markdown
Owner

Why

README's Quick Start is a 45-line inline snippet, but the runnable
program in cmd/quickstart had been growing into a 13-phase
~260-line end-to-end walk-through. The two pieces drift
independently:

  • 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).
  • The program had been refined to cover every exported symbol in
    a single go run and to demonstrate the documented API
    contract 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 WithTimeout
demonstrably resets on the happy path (the select hits the Ch
branch, never the ErrCh one).

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, same
output. 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

  • README's Quick Start is rewritten to be 1:1 with the new
    simplified binary.
  • 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.
  • CHANGELOG.md adds a ### Changed (examples split) section
    summarising the move.

What's not in this PR

  • No library code changes. All pubsub/ code is identical to
    main. The existing unit tests in pubsub/ remain the contract.
  • No CI changes. The existing .github/workflows/test.yml is
    the contract; both cmd/quickstart/main.go and
    cmd/quickstart-e2e/main.go already pass gofmt -l,
    go vet ./..., and go test -race -count=1 ./....

Verified locally

$ go run ./cmd/quickstart
Received: CPU over 90%!

$ go run ./cmd/quickstart-e2e
... (30-line transcript) ...
quickstart-e2e: ok

$ go build ./...               ok
$ go vet ./...                 clean
$ gofmt -l $(git ls-files)     clean
$ go test -race -count=1 ./... 3.1s, green

F2077 added 2 commits June 13, 2026 22:13
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
@F2077
F2077 merged commit 350ccb1 into main Jun 13, 2026
1 check passed
@F2077
F2077 deleted the split/quickstart-e2e branch June 13, 2026 14:35
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