mirror of
https://github.com/moltbot/moltbot.git
synced 2026-03-21 16:41:56 +00:00
166 lines
3.4 KiB
Markdown
166 lines
3.4 KiB
Markdown
---
|
|
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.
|