From 37276ff6bb70ffe9ec1ce313ad0769d975fa7439 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 8 Oct 2026 09:32:57 -0600 Subject: [PATCH 1/2] docs: vouch from first PR, require repro steps and UI screenshots --- .github/ISSUE_TEMPLATE/bug-report.md | 11 ++ .github/ISSUE_TEMPLATE/config.yml | 8 +- .github/ISSUE_TEMPLATE/introduce-yourself.md | 32 ------ .github/pull_request_template.md | 31 ++++- .github/workflows/vouch.yml | 17 +-- AGENTS.md | 26 ++++- CONTRIBUTING.md | 114 +++++++++++++++++-- README.md | 6 +- 8 files changed, 184 insertions(+), 61 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/introduce-yourself.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index c8296318e6..93dc43ee49 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -11,6 +11,17 @@ labels: bug, Needs Feedback **Steps to reproduce** + + +**Reproduces on play.hyperdx.io?** + 1. 2. 3. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 4d5832b679..cfa0fd29cf 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -6,6 +6,8 @@ contact_links: url: https://discord.gg/FErRRKU78j about: For usage questions, setup help, and general discussion, ask on Discord. - - name: First-time contributor? Introduce yourself - url: https://github.com/hyperdxio/hyperdx/issues/new?template=introduce-yourself.md - about: Say hello and get vouched before your first pull request. + - name: First-time contributor? + url: https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md#getting-vouched + about: + No need to open an issue to get vouched. Open your pull request and a + maintainer vouches from there. diff --git a/.github/ISSUE_TEMPLATE/introduce-yourself.md b/.github/ISSUE_TEMPLATE/introduce-yourself.md deleted file mode 100644 index 1b074daf95..0000000000 --- a/.github/ISSUE_TEMPLATE/introduce-yourself.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -name: Introduce yourself -about: Say hello and get vouched so you can open pull requests -title: 'Hello, I am ' -labels: introduction ---- - -Tell us a bit about yourself before your first pull request. A couple of -sentences is plenty. - -**Who are you?** - -**What would you like to work on?** - - - -**Anything we can help with?** - - - ---- - -A maintainer will reply and vouch for you, usually within a day or two. Then you -can open pull requests as normal. CONTRIBUTING.md has the dev setup if you want -to get started in the meantime. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 20e00f5778..0265ffc27f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,8 +8,10 @@ Write for reviewers who may not be familiar with this area of the product. ### Screenshots or video @@ -18,6 +20,31 @@ Omit this section if the PR does not contain any UI changes. | :----- | :---- | | | | +### How to reproduce + + + +**Starting point:** + + + +**On `main`:** + +1. + +**On this branch:** + +1. + ### How to test on Vercel preview ` comment diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e22f119268..e0effa2a95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,18 @@ Issues, bug reports and discussion are open to everyone. Pull requests are a little different: a maintainer has to vouch for you before we review your first -one. Open a PR without being vouched and it stays open — a bot adds a -`needs-vouch` label and a comment pointing you back here. Nothing gets closed, -you just aren't in the review queue yet. +one. + +**Your first pull request is how you get vouched.** There's no separate request +to file and nothing to do up front. Pick an issue, write the change, and open +the PR. A bot adds a `needs-vouch` label and a comment; a maintainer looks at +the PR, and if it's a real attempt at the problem they comment `/vouch` on it +and review it from there. Nothing gets closed while you wait. + +Please don't open an issue just to ask to be vouched. We vouch for people based +on a contribution, not an introduction, and requests without a PR attached get +closed. If you want a steer before writing code, ask on the issue you plan to +fix or on [Discord](https://discord.gg/FErRRKU78j). **One at a time.** Outside contributors can have one pull request open at once, or three once vouched. Open more than that and the newest is closed with a note @@ -15,11 +24,10 @@ don't count towards the limit. This isn't about the quality of your work — a handful of parallel changes from one author is more than we can review properly, and in practice it means none of them get merged. -To get vouched, [open an issue saying -hello](https://github.com/hyperdxio/hyperdx/issues/new?template=introduce-yourself.md): -who you are and what you want to work on. A maintainer replies, usually within a -day or two. Use the same issue to ask which issue to pick up, or to check an -approach before you write code. +What makes a first PR easy to vouch for: it references an `Accepting PR` issue, +explains why the change is needed, includes [reproduction +steps](#reproducing-issues-and-prs), and has [before/after +screenshots](#ui-changes-need-beforeafter-screenshots) if it touches the UI. Good places to start: the [good first issue](https://github.com/hyperdxio/hyperdx/labels/good%20first%20issue) label, @@ -27,13 +35,17 @@ and [Discord](https://discord.gg/FErRRKU78j) if the dev setup gives you trouble. Why we do this: AI tools make it cheap to open a plausible-looking PR with no understanding behind it, and reviewing those crowds out the contributions we -want to spend time on. Vouching is a short introduction, not a skill test. We -use [Vouch](https://github.com/mitchellh/vouch); the list is -[`.github/VOUCHED.td`](./.github/VOUCHED.td). +want to spend time on. Vouching is a check that there's a person behind the +work, not a skill test. We use [Vouch](https://github.com/mitchellh/vouch); the +list is [`.github/VOUCHED.td`](./.github/VOUCHED.td). ### Vouching someone (maintainers) -Comment on any issue or PR with the keyword first on the first line: +Vouch from the contributor's open pull request, once you've looked at it and +it's a genuine attempt at the problem. Don't vouch from an issue that has no PR +behind it; point the author here instead. + +Comment with the keyword first on the first line: ``` /vouch @username optional reason @@ -77,6 +89,84 @@ ask on the issue — that's usually what unblocks it. This is a convention, not hard gate: it keeps effort pointed at changes we've agreed on, on top of the vouching trust check above. +## Reproducing issues and PRs + +Every bug report and every PR needs steps someone else can follow to see the +problem (or the fix) for themselves. If a maintainer can't reproduce it, they +can't triage the issue or review the PR. + +**Try the demo environment first.** [play.hyperdx.io](https://play.hyperdx.io) +is a hosted HyperDX connected to a public demo dataset (logs, traces, metrics +and session replays from the OpenTelemetry demo app). If your bug shows up +there, link the exact URL — search and chart explorer keep their query, filters +and time range in the URL — and that's most of the repro. + +**If it needs your own setup, reproduce it locally against the demo data.** The +quickest way is the frontend in local mode, which needs no Docker and no +account: + +1. Run `yarn app:dev:local` and open the app URL it prints. +2. On the onboarding screen, click **Connect to Demo Server**. This adds a + `Demo` connection and the Demo Logs, Traces, Metrics and Sessions sources, + the same data play.hyperdx.io uses. Connections and sources live in your + browser's local storage; clear site data to start over. +3. Follow your steps from there. + +This is the same mode the Vercel preview on your PR runs in, so reviewers can +follow the same steps there. + +Local mode has no API behind it (dashboards and saved searches are kept in local +storage), so it can't reproduce anything involving alerts, webhooks, auth, +teams, or the API itself. For those, use the full stack (`yarn dev`, see +[Development](#development)). It sets up a `Local ClickHouse` connection and +sources for every new team, so onboarding skips the demo server button. To +point it at the demo data instead, add a connection in **Team Settings** with +host `https://sql-clickhouse.clickhouse.com`, user `otel_demo`, and an empty +password, then add sources on it from database `otel_v2` (tables `otel_logs`, +`otel_traces`, `hyperdx_sessions`, and the `otel_metrics_*` tables). Otherwise +it only has the data your local stack sends to itself (see `HYPERDX_API_KEY` +under [Development](#development)). + +If the bug depends on your own schema or data, say so, and include the table +definition (`SHOW CREATE TABLE ...`) and the source settings. Strip anything +sensitive. + +**What good steps look like:** + +- Start from a known place: play.hyperdx.io, `yarn app:dev:local` connected to + the demo server, or a fresh `yarn dev` (say which). +- Number each step and name the UI element you interact with by its visible + text: "Open **Search**, pick the **Demo Logs** source, set the time range to + **Last 15 minutes**, type `SeverityText:error` and press Enter." +- End with what you expected and what happened instead. +- For bugs, add the debug info from **Help → Copy debug info**. + +**In a PR**, fill in the "How to reproduce" section of the template with: + +- Steps that show the bug or missing behavior on `main` (or a link to the issue + that has them). +- The same steps on your branch, and what's different now. +- Anything extra the reviewer needs: env vars, a feature flag, a particular + source or schema, seed data. + +## UI changes need before/after screenshots + +Any PR that changes something a user can see in the app must include before and +after screenshots, or a short video if the change involves interaction or +animation. Put them in the "Screenshots or video" table of the PR template. + +- **Before** is `main`; **after** is your branch. Take both at the same + viewport size and theme, showing the same screen and data, so the difference + is obvious. The demo server data makes this easy. +- For a brand new screen or component there's no "before"; show the place it's + reached from instead. +- If the change affects both light and dark mode, or both the HyperDX and + ClickStack themes, include each one that looks different. +- Keep them focused. Crop to the area that changed, or annotate the full page. + +This isn't enforced by a check, but reviewers won't start on a UI PR without +them. + ## Architecture Overview ![architecture](./.github/images/architecture.png) diff --git a/README.md b/README.md index 3c1b60a07d..32e56a4c9f 100644 --- a/README.md +++ b/README.md @@ -145,9 +145,9 @@ including but not limited to: code we now use [Vouch](https://github.com/mitchellh/vouch): a maintainer has to vouch for you before your first pull request gets reviewed. AI tools make it cheap to open a plausible-looking PR with no understanding behind it, and -reviewing those crowds out the contributions we want to spend time on. Getting -vouched takes one issue — say hello and tell us what you want to work on. See -[Getting vouched](./CONTRIBUTING.md#getting-vouched). +reviewing those crowds out the contributions we want to spend time on. There's +nothing to request up front: open your first PR and a maintainer vouches for you +on it. See [Getting vouched](./CONTRIBUTING.md#getting-vouched). ## Motivation From c15eeeeb84ffd69b976271c2424d3853b598f3a7 Mon Sep 17 00:00:00 2001 From: Brandon Pereira Date: Thu, 8 Oct 2026 09:39:59 -0600 Subject: [PATCH 2/2] docs: note local-mode connections are session-scoped --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0effa2a95..5c22126a88 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -108,8 +108,9 @@ account: 1. Run `yarn app:dev:local` and open the app URL it prints. 2. On the onboarding screen, click **Connect to Demo Server**. This adds a `Demo` connection and the Demo Logs, Traces, Metrics and Sessions sources, - the same data play.hyperdx.io uses. Connections and sources live in your - browser's local storage; clear site data to start over. + the same data play.hyperdx.io uses. Connections and sources live in browser + storage; clear site data to start over. Connections last only for the browser + session, so reopening the app may require reconnecting to the demo server. 3. Follow your steps from there. This is the same mode the Vercel preview on your PR runs in, so reviewers can