Contributing¶

Conbench is maintained as a Go backend, Svelte dashboard, CLI-first write path, generated SDKs, and Markdown/Zensical documentation.

Core Commands¶

make go-fmt
make go-lint-ci
make go-test
make sqlc-check
make codegen-check
make build
make python-sdk-check
make migration-examples-test
make repo-hygiene-check
make docs-link-check
make build-docs

Use rg for code search and keep changes scoped to the requested behavior.

Repository Layout¶

The maintained source tree should stay explainable from the repository root:

• cmd/ and internal/ contain the Go server, CLI, services, storage, auth, generated sqlc code, and backend tests.
• web/ contains the Svelte dashboard source, generated TypeScript API types, and frontend tests.
• api/ contains generated OpenAPI contract artifacts reviewed with codegen changes and exposed by the server.
• sdk/ contains generated Go and Python SDKs. The Python SDK package is conbench; small hand-written helpers live in overlay files that are copied into the generated package by codegen.
• docs/site/ contains the public Markdown/Zensical documentation. Durable product, migration, and operations decisions belong there.
• examples/migration/ contains runnable migration recipes for old Python benchmark publishers moving to JSON payload files and the Go CLI.
• scripts/, k8s/, Dockerfiles, and Compose files contain local checks, packaging, smoke-test, and deploy-rendering support for the single conbench binary.

make repo-hygiene-check verifies that retired top-level Python package paths, single-file module names, and root Python application configuration files stay untracked. The remaining tracked Python files are intentionally scoped to schema migrations, generated SDK packaging, migration examples, and repository/documentation checks. The same check parses those active Python files and rejects imports from retired legacy packages such as benchadapt, benchconnect, benchalerts, benchclients, benchrun, conbenchlegacy, and conbench_client. It also rejects split command directories such as cmd/conbench-server and cmd/conbench-openapi; the maintained runtime and CLI surface belongs in the single conbench binary. scripts/retired_python_surfaces.py is the shared source of truth for retired Python package names, single-file module names, and path prefixes; update that file rather than duplicating package lists in workflow, repo, or artifact-hygiene checks.

Generated Artifacts¶

The Go structs and huma routes are the API source of truth. Regenerate OpenAPI and clients with:

make codegen

The database query layer is generated by sqlc:

make sqlc

Do not hand-edit generated client or sqlc files unless you are intentionally testing generator output and will regenerate before committing.

The Python SDK has one exception: small hand-written helpers live under sdk/python/overlays/conbench/ and are copied into the generated sdk/python/conbench/ package by make codegen-py. The expected overlay files are listed in sdk/python/overlays/manifest.txt; all package paths ever owned by the overlay system are listed in sdk/python/overlays/managed-targets.txt so retired helpers cannot remain packaged by accident. Edit the overlay source first, update both lists when adding or retiring an overlay file, then regenerate or copy it into the package. make python-sdk-check fails if the overlay source and packaged copy drift. The same package check builds the Python SDK wheel and sdist, then rejects retired package directories and single-file modules from built wheel and sdist artifacts before running clean-install smoke tests.

Documentation¶

Public docs are Markdown files under docs/site/ and are built by the Zensical version pinned in requirements-docs.txt. The Makefile checks the builder version before generating the site:

make docs-link-check
make build-docs
make docs-serve

make docs-link-check checks local links, heading anchors, documented Makefile target references, documented frontend package script references, migration coverage for the public migration pages, API and SDK page, SDK README, and root README, and Zensical navigation coverage. Every Markdown page under docs/site/ should be reachable from zensical.toml unless the checker has an explicit reason to exclude it.

Use the project issue tracker for active planning and work history. Durable product, migration, and operations decisions should be recorded in docs/site/ so the public docs stay the source of truth. Tracked documentation content belongs under docs/site/; implementation plans, scratch notes, and historical planning material should stay in the issue tracker or local ignored state unless they have been turned into public product, migration, or operations documentation.

.superpowers/ is local scratch state for companion mockups or temporary brainstorming artifacts. Do not commit it, and do not use it as a durable plan archive. Move decisions worth preserving into docs/site/ or record active work in the issue tracker.

Generated local artifacts such as site/, bin/, var/, .cache/, web/node_modules, Python cache directories, Python SDK build artifacts, built web/dist assets, and web test artifacts are ignored workspace state. They are useful for local verification, screenshots, and smoke tests, but they should not become tracked project files. Regenerate them from the documented Makefile or package-manager targets instead of treating local copies as source. Run make clean-local to remove those generated artifacts while keeping tracked placeholders such as web/dist/.gitkeep. The target also clears the Go build cache when Go is available, because deleted generated SPA assets can otherwise leave stale //go:embed cache metadata that names old hashed files.

Dashboard Product Principles¶

The Svelte dashboard is an operational benchmarking workbench. It should feel quiet, dense, and professional: optimized for scanning benchmark activity, finding regressions, comparing runs, and drilling into raw result metadata. Do not turn the dashboard into a marketing-style landing page, decorative card grid, or oversized hero surface.

Use these rules when changing dashboard UI:

• Preserve data density. Favor full-width tables, compact metric strips, filter bars, and contextual panels over large decorative cards.
• Keep workflow hierarchy clear. Every primary page should make the next investigation action obvious: browse series, inspect a result, compare two results, open a CI report, or export data.
• Treat long benchmark identifiers and metadata as first-class content. Names, tags, compiler flags, repositories, commits, hardware identifiers, and JSON payloads must wrap or scroll predictably without overlapping adjacent UI.
• Keep read-only public browsing separate from write capability. Write controls should render only when the server reports that the current browser context can perform the write.
• Preserve existing documented deep links while avoiding new legacy compatibility aliases unless they are explicitly approved. Visual refactors must not break route URLs that the migration guide already documents.
• Use restrained visual primitives: compact buttons, status badges, tabs, filter inputs, menus, and toolbars. Avoid decorative backgrounds and non-actionable explanatory text inside the application.
• Reuse shared components for page headers, toolbars, empty/error/loading states, data tables, status badges, key-value facts, and JSON panels instead of restyling each route independently.
• Keep core controls keyboard reachable with visible focus and stable accessible names. Navigation links, search, filters, tabs, menus, action buttons, and result/CI links should be testable by role and label.
• Verify responsive behavior on realistic data, including production-shaped long names and metadata. Desktop and mobile screenshots should show no clipped text, incoherent horizontal overflow, or overlapping controls.

Run make docs-screenshots before claiming a visual refresh is ready for review. The Docker-based target starts an isolated seeded Compose stack, captures dashboard screenshots from a pinned Playwright container into ignored files under docs/site/assets/screenshots/, writes dashboard-screenshots-evidence.json, and tears the stack down. The screenshots are documentation assets and a lightweight evidence trail for the product's current look and responsive behavior, but generated PNGs belong on the orphan docs-screenshots branch or in CI artifacts rather than in the main branch history. The JSON evidence records the captured routes, viewports, dimensions, byte sizes, SHA-256 digests, and isolation/quality checks. The capture also asserts painted charts, no desktop document overflow, visible mobile navigation, scrubbed volatile result IDs, and no leaked internal screenshot origin. CI runs the same screenshot capture path, checks the generated artifact directory for complete, nonblank PNGs, verifies that the Docker image uses the same exact Playwright pin as the web package, uploads those PNGs and the evidence JSON as the conbench-dashboard-screenshots artifact, and publishes latest push captures to the orphan screenshot branch for the Pages build to restore.