contributing.md

Contributing

Contributions are welcome, including pull requests from forks. You do not need write access to kenn-io/benchdb to contribute.

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

Submit a pull request from a fork

1. Fork kenn-io/benchdb on GitHub.

2. Clone your fork and add BenchDB as the upstream remote. Replace YOUR-USERNAME with your GitHub username:

   git clone https://github.com/YOUR-USERNAME/benchdb.git
   cd benchdb
   git remote add upstream https://github.com/kenn-io/benchdb.git
   git fetch upstream
   git switch -c my-change upstream/main

3. Make your changes and run the relevant checks below. Read the repository's AGENTS.md for standing rules and required checks, including when working with a coding agent.

4. Commit your changes, confirm that origin points to your fork, and push:

   git remote -v
   git push -u origin my-change

5. Open a pull request with base repository kenn-io/benchdb, base branch main, and head branch YOUR-USERNAME:my-change. With the GitHub CLI:

   gh pr create --repo kenn-io/benchdb --base main --head YOUR-USERNAME:my-change

For an existing checkout, inspect the remote URLs before pushing; remote names alone do not establish which repository they point to. Maintainers with write access may use a feature branch in kenn-io/benchdb instead of a fork. Keep each contribution focused and open one pull request by default.

BenchDB is developed independently of Conbench. Send BenchDB issues and pull requests to kenn-io/benchdb, not to the original Conbench repository.

Core Commands

make go-fmt
make go-lint-ci
make go-test
make sqlc-check
make codegen-check
make build
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 the generated Go client.
• docs/site/ contains the public Markdown/Zensical documentation. Durable product, migration, and operations decisions belong there.
• scripts/, k8s/, Dockerfiles, and Compose files contain local checks, packaging, smoke-test, and deploy-rendering support for the single benchdb binary.

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.

Database Migrations

Number migrations sequentially under internal/db/migrations and provide matching .up.sql and .down.sql files. After the initial history bootstrap, a pull request adds at most one migration; amend that migration before it ships, and never edit migration files already present on the target branch. Run make migration-history-check before committing. sqlc reads the same migration directory, so schema changes and query generation have one source of truth.

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 client page, 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, 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.

Website deployment

The website is deployed through Vercel's CLI. Its GitHub workflow checks the complete tiered site but does not publish it.

Link the repository root to the benchdb.io project once:

vercel link --yes --team kenn-software --project benchdb.io

Then build and deploy the exact local artifact:

make site-deploy

The build hydrates the curated product screenshot from the docs-assets branch, renders the product, guide, and reference layers, and stages that result as a prebuilt static Vercel deployment.

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 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, and uploads those PNGs and the evidence JSON as the benchdb-dashboard-screenshots artifact. Release-ready captures live on the orphan docs-screenshots branch. The website workflow checks out and verifies that inventory before it builds the Vercel output. The orphan docs-assets branch remains limited to the curated product screenshot used by the marketing home page.