Documentation
¶
Overview ¶
Package report renders the root README's `## Performance` block from the committed benchmark outputs (results.json, footprint.json, metadata.json) and replaces the content between the benchmark-results markers. Generation is one-directional (issue #141 §9: Markdown is derived, never hand-authored), so `make benchmark-report` writes it and `make benchmark-report-check` (InSync) reports drift when the committed README no longer matches the data. CI runs that check (the `benchmark-report-drift` job in .github/workflows/ci.yml).
The CRUD table reuses benchmarks/internal/summary for the per-(framework, concurrency) median, so the headline figure here and in summary.md come from the same code.
Index ¶
Constants ¶
const ( // StartMarker / EndMarker bracket the generated block in README.md. They are // HTML comments so they render invisibly. StartMarker = "<!-- benchmark-results:start -->" EndMarker = "<!-- benchmark-results:end -->" // HeadlineConcurrency is the client count the README CRUD table publishes // (issue #141 §13 B is a single headline row, not a per-concurrency dump). // If a run doesn't have this level, the table falls back to the highest // concurrency present; the caption always states which was used. HeadlineConcurrency = 100 )
Variables ¶
var CanonicalProtocol = Protocol{ Concurrency: []int{1, 10, 100, 500, 1000}, Trials: 5, DurationSeconds: 30, WarmupSeconds: 10, }
CanonicalProtocol is the full dedicated-host run the methodology describes (issue #141 §13), pinned in benchmarks/config/versions.env. A snapshot whose metadata differs from this is labelled a reduced development snapshot in the generated README so its numbers are never mistaken for the canonical run. report_test.go asserts these stay in sync with versions.env, so the single source of truth (the env file) can't drift away from this comparison silently.
Functions ¶
func InSync ¶
InSync reports whether the block currently between the markers in readme already equals what Render produced (trailing whitespace normalised) — i.e. true means no drift, so a caller reads `if !InSync { fail }`. A missing marker is treated as out of sync (returns false with the marker error).
func Render ¶
func Render(results []result.Result, prints []footprint.Footprint, micro []microbench.Row, meta metadata.Metadata) string
Render returns the Markdown block (without the markers) for the given data. Any section with no data renders an honest "not yet recorded" line rather than an empty table, so the generator is runnable before the canonical run.
func ReplaceBlock ¶
ReplaceBlock returns readme with the content between the markers replaced by block (a trailing newline is normalised). It errors if either marker is missing or they are out of order.
Source Files