Skip to content

docs(concepts): consolidated Performance page#138

Merged
lesnik512 merged 1 commit into
mainfrom
docs-performance-page
Jul 16, 2026
Merged

docs(concepts): consolidated Performance page#138
lesnik512 merged 1 commit into
mainfrom
docs-performance-page

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Adds a single user-facing Performance page (docs/concepts/performance.md) that ties the three 0.11.0 performance levers together, so a reader asking "my outbox is slow / bloating, what do I turn?" finds the answer in one place.

Design of record: planning/changes/2026-07-16.03-performance-docs-page.md.

What it is

A hub — it owns the synthesis and links out to the existing mechanics; no content moves.

  • The cost model — round-trips + table churn, in a paragraph.
  • What each lever buys — a two-column benchmark table: CI-gated deterministic statement counts (pg_notify 5000→1, terminal DELETEs 5000→50) vs illustrative loopback wall-clock (~1.9× bulk publish, batched-worker-beats-4-workers), explicitly labeled machine-dependent. A note defines the distinction.
  • Which knob for which workload — the decision table (the centerpiece).
  • The three levers — one tight subsection each (NOTIFY dedup / batched terminal flush / autovacuum), linking to How it works, subscriber.md#batching-terminal-deletes, and alembic.md#autovacuum-tuning-recommended.
  • Measuring it yourself — the benchmarks/ harness, what baseline.json gates, and that wall-clock is machine-dependent.

Two back-links added (subscriber batching + Alembic autovacuum sections) so reference readers find the hub. Nav: new Performance entry under Concepts.

Notes

  • Links stay inside docs/ — no links to architecture/*.md (outside the mkdocs tree, would fail strict build).
  • Honesty guardrail: no wall-clock figure appears without its "loopback, one-off, machine-dependent" caveat; the gated statement-count column is the credible spine.

Verification

  • just docs-build (mkdocs build --strict, validation.anchors: warn → error) clean — all three #fragment anchors resolve.
  • just lint-ci — ruff + ty + planning validator (planning: OK) clean.

Docs-only, no code or behavior change.

🤖 Generated with Claude Code

Add docs/concepts/performance.md, a hub tying the three 0.11.0 performance
levers together: NOTIFY dedup, batched terminal flush, and autovacuum tooling.
Owns the synthesis (a which-knob-for-which-workload table and a two-column
benchmark table separating CI-gated statement counts from illustrative
loopback wall-clock); links to the existing mechanics rather than moving them.

Back-links added from the subscriber batching and Alembic autovacuum sections.
Design: planning/changes/2026-07-16.03-performance-docs-page.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@lesnik512
lesnik512 merged commit dffa349 into main Jul 16, 2026
7 checks passed
@lesnik512
lesnik512 deleted the docs-performance-page branch July 16, 2026 20:02
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