Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/ISSUE_TEMPLATE/bug-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,17 @@ labels: bug, Needs Feedback

**Steps to reproduce**

<!--
Please check whether this reproduces on https://play.hyperdx.io (demo data) and
paste the URL if it does. If you're working from the repo, `yarn app:dev:local`
plus onboarding → "Connect to Demo Server" gives you the same data locally. If
it only happens with your own data, include the table schema
(`SHOW CREATE TABLE ...`) and source settings.
See https://github.com/hyperdxio/hyperdx/blob/main/CONTRIBUTING.md#reproducing-issues-and-prs
-->

**Reproduces on play.hyperdx.io?** <!-- yes (link) / no / didn't try -->

1.
2.
3.
Expand Down
8 changes: 5 additions & 3 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
32 changes: 0 additions & 32 deletions .github/ISSUE_TEMPLATE/introduce-yourself.md

This file was deleted.

31 changes: 29 additions & 2 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,10 @@ Write for reviewers who may not be familiar with this area of the product.
### Screenshots or video

<!--
If this PR includes UI changes, include screenshots or a short video.
For new features, "Before" can be omitted.
Required for any PR that changes something visible in the UI. Before is main,
after is this branch: same screen, data, viewport, and theme. Use a short video
for interactions. For a brand new screen, show where it's reached from as
"Before". See CONTRIBUTING.md#ui-changes-need-beforeafter-screenshots.

Omit this section if the PR does not contain any UI changes.
-->
Expand All @@ -18,6 +20,31 @@ Omit this section if the PR does not contain any UI changes.
| :----- | :---- |
| | |

### How to reproduce

<!--
Steps a reviewer can follow to see the problem on main and the fix on this
branch. Start from play.hyperdx.io where possible, or `yarn app:dev:local`
connected to the demo server (onboarding → "Connect to Demo Server"); the
Vercel preview on this PR runs the same local mode. Use `yarn dev` only when
the change needs the API (alerts, webhooks, auth, teams). Name UI
elements by their visible text. List any env vars, feature flags, schema, or
seed data needed. Linking an issue that already has repro steps is fine.
See CONTRIBUTING.md#reproducing-issues-and-prs.
-->

**Starting point:**

<!-- play.hyperdx.io URL, or local dev + demo server, or your own setup (describe it) -->

**On `main`:**

1.

**On this branch:**

1.

### How to test on Vercel preview

<!--
Expand Down
17 changes: 10 additions & 7 deletions .github/workflows/vouch.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ name: Vouch
# are on the vouch list. Anything over that is closed, asking them to
# finish what they have open first. Drafts don't count.
# 2. Authenticity. A PR from someone not in .github/VOUCHED.td stays open but
# gets a `needs-vouch` label and a comment asking them to introduce
# themselves.
# gets a `needs-vouch` label and a comment saying a maintainer will vouch
# from the PR itself. The first PR is the introduction; we don't ask for
# a separate issue, which mostly attracted vouch requests with no code.
#
# Authors explicitly denounced in the list are always closed. Issues are NOT
# gated — opening one is how a new contributor introduces themselves.
# gated.
#
# Maintainers manage the list from any issue or PR comment. The keyword has to
# be first on the first line:
Expand Down Expand Up @@ -145,13 +146,15 @@ jobs:
const body = [
`Hi @${pr.user.login}, thanks for the pull request!`,
``,
`Before we review code from a first-time contributor we ask that a maintainer vouches for you, and you're not on our list yet. **This PR stays open** — it just isn't in the review queue until someone vouches.`,
`Before we review code from a first-time contributor, a maintainer vouches for them, and you're not on our list yet. **There's nothing else to file and this PR stays open** — a maintainer will look at it, usually within a day or two, and vouch for you right here if it's a genuine attempt at the problem.`,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 minor — needs-vouch label is never removed after a maintainer vouches on the PR, which is now the normal path

Under the old flow most contributors got vouched before opening a PR, so the label was uncommon. Now every first PR gets needs-vouch, and nothing ever clears it. check-pr only runs on opened/reopened/ready_for_review, and the manage job (manage-by-issue, line 191) only opens a VOUCHED.td PR. A grep of .github/ finds no other code that touches the label. Vouched PRs stay labelled and look like they are still out of the review queue. Fix: in the manage job, after a successful /vouch on a PR (github.event.issue.pull_request is set), call issues.removeLabel for needs-vouch. Alternatively, have check-pr drop the label when status is vouched.

Advisory. Fix if it is a small defect in code this PR changes; otherwise reply in the thread. Do not widen the PR or touch files it did not already change. How to respond

``,
`To get vouched, open an issue saying hello and what you're working on:`,
`To make that quick, check the PR description has:`,
``,
`https://github.com/${owner}/${repo}/issues/new?template=introduce-yourself.md`,
`- The issue it addresses (ideally one labelled \`Accepting PR\`) and why the change is needed`,
`- Steps to reproduce the problem and verify the fix, starting from https://play.hyperdx.io or \`yarn app:dev:local\` connected to the demo server`,
`- Before/after screenshots if anything in the UI changed`,
``,
`A maintainer will usually reply within a day or two, and then this PR gets picked up as normal. More detail in [our contributing guide](https://github.com/${owner}/${repo}/blob/${pr.base.repo.default_branch}/CONTRIBUTING.md#getting-vouched).`,
`More detail in [our contributing guide](https://github.com/${owner}/${repo}/blob/${pr.base.repo.default_branch}/CONTRIBUTING.md#getting-vouched).`,
].join('\n');
await github.rest.issues.createComment({
owner, repo, issue_number: pr.number, body,
Expand Down
26 changes: 24 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -247,15 +247,37 @@ efficient and accurate:
your agent to produce tests before writing implementation code. See the
Testing section below for the commands to use.

5. **Ensure a changeset exists before pushing a PR.** Any change to a published
5. **Attach before/after screenshots to any PR that changes the UI.** Anything
visible in `packages/app` needs a "Before" (`main`) and "After" (branch)
image in the PR template's screenshots table, taken on the same screen, data,
viewport, and theme. Use a short video for interactions. If you can't capture
screenshots yourself (no browser tool), say so in the PR description and
leave the table for the human author to fill; never submit an empty table
silently. See
[CONTRIBUTING.md](CONTRIBUTING.md#ui-changes-need-beforeafter-screenshots).

6. **Write reproduction steps a reviewer can follow.** Fill in the PR
template's "How to reproduce" section with numbered steps that show the
problem on `main` and the fix on the branch. Start from
[play.hyperdx.io](https://play.hyperdx.io) when the bug shows there, or from
`yarn app:dev:local` connected to the demo server (onboarding → "Connect to
Demo Server"; the PR's Vercel preview runs the same local mode). Full-stack
`yarn dev` pre-provisions a local ClickHouse connection and never shows that
button, so use it only when the change needs the API. Name UI elements by
visible text, and list any env vars,
feature flags, schema, or seed data needed. When filing issues, apply the
same standard. See
[CONTRIBUTING.md](CONTRIBUTING.md#reproducing-issues-and-prs).

7. **Ensure a changeset exists before pushing a PR.** Any change to a published
package (`@hyperdx/app`, `@hyperdx/api`, `@hyperdx/otel-collector`, etc.) that
is user-facing or affects behavior must include a changeset in `.changeset/`.
Add one with `yarn changeset` (or create the markdown file by hand following
the format of existing entries), choosing the appropriate semver bump, before
pushing the branch. Skip only for changes that don't warrant a release (docs,
internal tooling, tests, CI).

6. **The root `CHANGELOG.md` is generated at release time.** During each
8. **The root `CHANGELOG.md` is generated at release time.** During each
release, CI writes an AI-generated cross-package summary section into the
root `CHANGELOG.md` on the "Release HyperDX" PR. Review and edit it there
like any other file — but keep the `<!-- hyperdx-release-notes … -->` comment
Expand Down
115 changes: 103 additions & 12 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -15,25 +24,28 @@ 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,
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
Expand Down Expand Up @@ -77,6 +89,85 @@ 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 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
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)
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading