Skip to main content
Version: Next 🚧

Contributing

Thanks for considering a contribution. This project is small but maintained — every well-scoped issue, dashboard, doc fix, and code change moves it forward.

Three pages cover everything you'll need:

Ways to contribute​

Multiple paths beyond code. File a high-signal bug, propose a new metric, share a Grafana dashboard, improve docs, sponsor. Start here if you're new.

Architecture​

Why the code is shaped the way it is. The two-tier scrape, the eager-kickoff promise pattern, JS-side joins instead of $lookup, cardinality gates, ESM/NodeNext gotchas. Read this before any non-trivial code change — it'll save you reviewer round-trips.

Adding a metric​

Step-by-step playbook for the most common code contribution: adding a new metric. Covers tier selection (basic vs advanced), the cardinality budget, where to put the code, indexes, tests, and docs.

Cutting a release (maintainers)​

The release is mostly automated. Two steps:

  1. Prepare: Actions tab → "Prepare release" workflow → Run workflow → enter the new version (e.g. 0.9.0). The workflow snapshots the docs site, bumps package.json, and opens a PR. Review, merge.
  2. Tag: after the release PR merges, tag the merge commit and push (git tag v0.9.0 origin/main && git push origin v0.9.0) — or use the GitHub UI's "Draft a new release" flow.

CD takes over: multi-arch build, cosign sign, attest build-provenance + SBOM, Trivy scan, attach SBOM to the Release. The docs site re-deploys with the new version snapshot visible in the versions dropdown.

Ground rules​

  • All contributions are MIT-licensed (see LICENSE).
  • Be excellent — see CODE_OF_CONDUCT.md.
  • Security issues — please use the private security advisory flow, not a public issue. Full process: SECURITY.md.
  • Disclose AI usage — if a contribution was substantially generated by an AI assistant, mention it in the PR description. Not a problem; we just want it noted.