Docs: add PR and issue submission guides (#10150)

* Docs: add PR and issue submission guides * Docs: fix LLM-assisted wording
2026-06-28 19:01:47 +03:00 · 2026-02-05 23:59:47 -06:00
parent 4a59b7786b
commit 50e687d17d
4 changed files with 382 additions and 1 deletions
@@ -0,0 +1,165 @@
+---
+summary: "How to file high signal issues and bug reports"
+title: "Submitting an Issue"
+---
+
+# Submitting an Issue
+
+Good issues make it easy to reproduce, diagnose, and fix problems quickly. This guide covers what to include for bugs, regressions, and feature gaps.
+
+## What makes a good issue
+
+- [ ] Clear title: include the area and the symptom.
+- [ ] Repro steps: minimal steps that consistently reproduce the issue.
+- [ ] Expected vs actual: what you thought would happen and what did.
+- [ ] Impact: who is affected and how severe the problem is.
+- [ ] Environment: OS, runtime, versions, and relevant config.
+- [ ] Evidence: logs, screenshots, or recordings (redacted; prefer non-PII data).
+- [ ] Scope: note if it is new, regression, or long-standing.
+- [ ] Code word: include “lobster-biscuit” somewhere in the issue description to confirm you read this guide.
+- [ ] Due diligence: search the codebase for existing functionality and check GitHub to see if the issue is already filed or fixed.
+- [ ] I searched for existing and recently closed issues/PRs.
+- [ ] For security reports: confirmed it has not already been fixed or addressed recently.
+- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
+
+Guideline: concision > grammar. Be terse if it makes review faster.
+
+Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
+
+- `pnpm lint`
+- `pnpm check`
+- `pnpm build`
+- `pnpm test`
+- If you touch protocol code: `pnpm protocol:check`
+
+## Templates
+
+### Bug report
+
+```md
+## Bug report checklist
+
+- [ ] Minimal repro steps
+- [ ] Expected vs actual
+- [ ] Versions and environment
+- [ ] Affected channels and where it does not reproduce
+- [ ] Logs or screenshots
+- [ ] Evidence is redacted and non-PII where possible
+- [ ] Impact and severity
+- [ ] Any known workarounds
+
+## Summary
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+
+## Workarounds
+```
+
+### Security issue
+
+```md
+## Summary
+
+## Impact
+
+## Affected Versions
+
+## Repro Steps (if safe to share)
+
+## Mitigation or Workaround
+
+## Evidence (redacted)
+```
+
+Security note: avoid posting secrets or exploit details in public issues. If the report is sensitive, keep repro details minimal and ask for a private disclosure path.
+
+### Regression report
+
+```md
+## Summary
+
+## Last Known Good
+
+## First Known Bad
+
+## Repro Steps
+
+## Expected
+
+## Actual
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+### Feature request
+
+```md
+## Summary
+
+## Problem
+
+## Proposed Solution
+
+## Alternatives Considered
+
+## Impact
+
+## Evidence or Examples
+```
+
+### Enhancement request
+
+```md
+## Summary
+
+## Current Behavior
+
+## Desired Behavior
+
+## Why This Matters
+
+## Alternatives Considered
+
+## Evidence or Examples
+```
+
+### Investigation request
+
+```md
+## Summary
+
+## Symptoms
+
+## What Was Tried
+
+## Environment
+
+## Logs or Evidence
+
+## Impact
+```
+
+## If you are submitting a fix PR
+
+Creating a separate issue first is optional. If you skip it, include the relevant details in the PR description.
+
+- Keep the PR focused on the issue.
+- Include the issue number in the PR description.
+- Add tests when possible, or explain why they are not feasible.
+- Note any behavior changes and risks.
+- Include redacted logs, screenshots, or videos that validate the fix.
+- Run relevant `pnpm` validation commands and report results when appropriate.