Skip to content

docs(github): add debug-info ask and Needs Feedback issue flow - #3239

Merged
kodiakhq[bot] merged 2 commits into
mainfrom
claude/issue-template-needs-feedback
Sep 28, 2026
Merged

kodiakhq[bot] merged 2 commits into
mainfrom
claude/issue-template-needs-feedback

Conversation

@brandon-pereira

Copy link
Copy Markdown
Member

Why

Two intake improvements requested for the issue templates:

  1. Collect debug info up front. UI bug reports rarely include version/deployment/browser context, causing back-and-forth. The app already has a Help → Copy debug info feature that dumps exactly this (frontend/backend version, deployment mode, browser, session id; API keys and query params are stripped).
  2. Move toward "approved" issues before code. We want a clear signal that an issue's scope is settled before anyone opens a PR, so effort isn't wasted on changes we haven't agreed on.

What changed

  • bug-report.md — new Debug info section pointing to Help → Copy debug info, with a paste block. Strongly requested for UI bugs, N/A for collector/CLI. Also auto-labels new bugs Needs Feedback.
  • feature-request.md (new) — problem / proposal / alternatives / extras; auto-labels enhancement, Needs Feedback; explains the flow.
  • config.yml (new) — disables blank issues so every issue starts from a template (and picks up Needs Feedback); adds Discord + introduce-yourself contact links.
  • CONTRIBUTING.md — new "From issue to pull request" section: Needs Feedback = still discussing, don't PR yet; a maintainer swaps it for Accepting PR = ready to pick up. Convention layered on top of the existing vouch trust gate — no PR-side enforcement.

Flow

Issue opens (Needs Feedback)  ->  maintainer discussion  ->  swap to Accepting PR  ->  contributor claims + PRs

Label swap is manual by design (no new workflow). Gating is convention + docs only.

Required follow-up (labels must exist)

Front-matter labels only apply if the label already exists in the repo. Create once:

gh label create "Needs Feedback" --color FBCA04 --description "Under discussion; not ready for a PR yet"
gh label create "Accepting PR" --color 0E8A16 --description "Scope agreed; ready to be picked up"

Note

blank_issues_enabled: false removes the "open a blank issue" escape hatch — that's what guarantees the label is applied. If maintainers rely on blank issues, drop that line (I can instead add a small backfill workflow to label unlabeled issues on open).

Not included

No changeset — .github templates + CONTRIBUTING.md only, no published-package behavior change.

Improve the issue intake in two ways:

- Bug report now strongly requests the Help -> Copy debug info block for UI
  bugs, so version/deployment/browser/session context arrives with the report.
- New issues start as `Needs Feedback` (auto-applied by the templates) and are
  only ready to be PR'd once a maintainer swaps that for `Accepting PR`. Adds a
  feature-request template, disables blank issues so every issue picks up the
  label, and documents the issue -> PR flow in CONTRIBUTING.md.
@vercel

vercel Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
hyperdx-oss Ready Ready Preview Sep 28, 2026 6:49pm UTC
hyperdx-storybook Ready Ready Preview Sep 28, 2026 6:49pm UTC

Request Review

@changeset-bot

changeset-bot Bot commented Sep 28, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 94a3088

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions github-actions Bot added the review/tier-2 Low risk — AI review + quick human skim label Sep 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🔵 Tier 2 — Low Risk

Small, isolated change with no API route or data model modifications.

Why this tier:

  • Standard feature/fix — introduces new logic or modifies core functionality

Review process: AI review + quick human skim (target: 5–15 min). Reviewer validates AI assessment and checks for domain-specific concerns.
SLA: Resolve within 4 business hours.

Stats
  • Production files changed: 1
  • Production lines changed: 11
  • Branch: claude/issue-template-needs-feedback
  • Author: brandon-pereira

To override this classification, remove the review/tier-2 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

@github-actions

Copy link
Copy Markdown
Contributor

Duplicate code analysis

No new duplicate code introduced by this PR.


jscpd compared this branch against origin/main
across app, api and common-utils. Only new clones are listed; the codebase
currently holds 128 in total (1.83%).
Run yarn dupes locally to reproduce, or yarn dupes:all for the full picture.

<!--
For UI bugs, please include this — it saves a lot of back-and-forth. Open the
Help menu (bottom-left of the app) and click "Copy debug info", then paste the
block below. It captures versions, deployment mode, browser, and session id; no

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 — Debug info blurb doesn't mention everything the report pastes into a public issue

The report built by buildReport() in packages/app/src/hdxDebug.ts:178-197 also includes the user id, team id, the current page path and the enabled feature flags, not just "versions, deployment mode, browser, and session id". The page path can contain dashboard or saved-search ids. List those fields in the comment (e.g. "…session id, your user/team id and current page path…") so people know what they're posting publicly and can redact it.

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

Comment thread CONTRIBUTING.md
issue**; the discussion often changes what the fix should be, and code written
too early tends to get thrown away.

Once a maintainer is happy with the direction, they swap `Needs Feedback` for

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 — New flow says nothing about existing issues and good first issue issues that have neither label

Only new issues get Needs Feedback. Existing open issues, including the good first issue list that CONTRIBUTING.md:24-25 and introduce-yourself.md recommend, have neither Needs Feedback nor Accepting PR, so it's unclear whether they're open for PRs. Add a sentence covering unlabeled or good first issue issues, or backfill Accepting PR on them.

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

@github-actions

Copy link
Copy Markdown
Contributor

PR Review

If you are a coding agent acting for the author, read this first.
Nothing below blocks merge automatically; a maintainer decides. What they will expect:

  • 🔴 critical or 🟠 major in code this PR adds or changes: fix before asking for review.
  • 🔵 minor in code this PR changes: your call. Fix if small, otherwise reply.
  • Anything about surrounding code, or asking you to widen the change (hoist a helper,
    dedupe with another file, fix other call sites): never fix here, whatever the
    severity. Reply with one sentence; if it is critical, say so plainly so a human sees it.

One commit per review round. After two rounds, stop and ask a maintainer to review
scope rather than addressing more automated findings. Full rule: AGENTS.md.

2 finding(s): 🔴 0 critical · 🟠 0 major · 🔵 2 minor

2 posted as inline comment(s) on the changed lines.


Severity is the reviewer's own estimate and is used for ordering, not filtering. No finding blocks merge automatically; a maintainer decides.

@github-actions

Copy link
Copy Markdown
Contributor

Deep Review

✅ No critical issues found.

This is a prose/config-only change to GitHub issue templates and CONTRIBUTING.md — no executable code, so runtime reviewers (security, performance, reliability, adversarial) were not applicable. The referenced assets all resolve: introduce-yourself.md and VOUCHED.td exist, the Copy debug info Help-menu feature exists in packages/app/src/components/AppNav/AppNav.components.tsx, the config.yml contact_links carry the required name/url/about fields, and the #from-issue-to-pull-request anchor matches the new heading.

🟡 P2 -- recommended

  • .github/ISSUE_TEMPLATE/bug-report.md:5 -- The intake flow depends on the Needs Feedback and Accepting PR labels existing in the repo, but GitHub silently drops template front-matter labels that are not already defined, so issues open unlabeled and the "discuss before PR" signal never appears.
    • Fix: Create both labels in the repository before or alongside merge so the front-matter labels: entries actually apply.
🔵 P3 nitpicks (2)
  • .github/ISSUE_TEMPLATE/bug-report.md:47 -- The bug report template auto-applies Needs Feedback but, unlike feature-request.md, never points the reporter at the issue→PR flow in CONTRIBUTING.md, so bug reporters get no explanation of what the label means.
    • Fix: Add the same closing pointer to CONTRIBUTING.md#from-issue-to-pull-request that feature-request.md uses.
  • CONTRIBUTING.md:60 -- The Needs Feedback → Accepting PR flow is described both here and in the feature-request.md footer, so the two copies can drift as the process evolves.
    • Fix: Keep the authoritative description in CONTRIBUTING.md and have the template link to it rather than restating the flow.

Reviewers (3): correctness, maintainability, project-standards.

Testing gaps: none — documentation and issue-template config carry no automated tests, and the label dependency above is validated by the repo's label configuration rather than code.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR. How to respond

@greptile-apps

greptile-apps Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Medium risk]

The PR has no newly identified blocking issue, though two earlier non-blocking documentation findings remain open.

Fix All in Claude CodeFindings

  1. P2 Debug info includes identifiers ▶
  2. P2 Label guarantee is overstated ▶

Summary

This PR adds debug-info guidance to bug reports and a Needs Feedback convention for bug reports and feature requests.

  • Adds a feature-request template and issue contact links.
  • Documents the manual transition to Accepting PR before contributors start work.
Diagram
%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["Bug report or feature request"] --> B["Needs Feedback"]
  B --> C["Maintainer agrees on scope"]
  C --> D["Accepting PR"]
  D --> E["Contributor claims issue and opens PR"]
Loading

Reviews (2) · Last reviewed commit: "Merge branch 'main' into claude/issue-te..."

Comment on lines +38 to +40
block below. It captures versions, deployment mode, browser, and session id; no
API keys or query params are included. Skip it if you're only hitting the
collector or CLI (write N/A).

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.

P2 Debug info includes identifiers The copied block also contains user and team IDs when available. Because reporters are asked to paste it into a public issue, please tell them to review or redact those IDs before posting. Otherwise, they may disclose account details unintentionally.

Suggested change
block below. It captures versions, deployment mode, browser, and session id; no
API keys or query params are included. Skip it if you're only hitting the
collector or CLI (write N/A).
block below. It captures versions, deployment mode, browser, session id, and
user and team IDs when available. No API keys or query params are included.
Review and redact identifiers before posting publicly. Skip it if you're only
hitting the collector or CLI (write N/A).

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

Comment on lines +1 to +2
# Blank issues are disabled so every issue starts from a template and picks up
# the `Needs Feedback` label. Use the templates or the links below.

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.

P2 Label guarantee is overstated Disabling blank issues does not make every new issue pick up Needs Feedback. The “Introduce yourself” template applies only introduction, and the new contact link opens that template. Narrow this comment to bug reports and feature requests so maintainers do not rely on a guarantee the configuration does not provide.

Suggested change
# Blank issues are disabled so every issue starts from a template and picks up
# the `Needs Feedback` label. Use the templates or the links below.
# Blank issues are disabled so new issues start from a template.
# Bug reports and feature requests pick up `Needs Feedback`; introduction
# issues use the `introduction` label. Use the templates or the links below.

Fix in Claude Code Fix in Conductor Fix in Cursor Fix in Codex

@github-actions

github-actions Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

E2E Test Results

✅ All tests passed • 385 passed • 1 skipped • 1305s

Status Count
✅ Passed 385
❌ Failed 0
⚠️ Flaky 1
⏭️ Skipped 1

Tests ran across 4 shards in parallel.

View full report →

@kodiakhq
kodiakhq Bot merged commit 3343082 into main Sep 28, 2026
29 checks passed
@kodiakhq
kodiakhq Bot deleted the claude/issue-template-needs-feedback branch September 28, 2026 18:53

This branch was successfully deployed

2 active deployments
Preview – hyperdx-oss — 94a30882 Deployed Sep 28, 2026 by vercel[bot]
Preview – hyperdx-storybook — 94a30882 Deployed Sep 28, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automerge review/tier-2 Low risk — AI review + quick human skim

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants