diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 82b560c473..0000000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: Bug report -about: Report a problem or unexpected behavior in Clawdbot. -title: "[Bug]: " -labels: bug ---- - -## Summary - -What went wrong? - -## Steps to reproduce - -1. -2. -3. - -## Expected behavior - -What did you expect to happen? - -## Actual behavior - -What actually happened? - -## Environment - -- Clawdbot version: -- OS: -- Install method (pnpm/npx/docker/etc): - -## Logs or screenshots - -Paste relevant logs or add screenshots (redact secrets). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000000..56a343c38d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,95 @@ +name: Bug report +description: Report a defect or unexpected behavior in OpenClaw. +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for filing this report. Keep it concise, reproducible, and evidence-based. + - type: textarea + id: summary + attributes: + label: Summary + description: One-sentence statement of what is broken. + placeholder: After upgrading to 2026.2.13, Telegram thread replies fail with "reply target not found". + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: Provide the shortest deterministic repro path. + placeholder: | + 1. Configure channel X. + 2. Send message Y. + 3. Run command Z. + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What should happen if the bug does not exist. + placeholder: Agent posts a reply in the same thread. + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What happened instead, including user-visible errors. + placeholder: No reply is posted; gateway logs "reply target not found". + validations: + required: true + - type: input + id: version + attributes: + label: OpenClaw version + description: Exact version/build tested. + placeholder: 2026.2.13 + validations: + required: true + - type: input + id: os + attributes: + label: Operating system + description: OS and version where this occurs. + placeholder: macOS 15.4 / Ubuntu 24.04 / Windows 11 + validations: + required: true + - type: input + id: install_method + attributes: + label: Install method + description: How OpenClaw was installed or launched. + placeholder: npm global / pnpm dev / docker / mac app + - type: textarea + id: logs + attributes: + label: Logs, screenshots, and evidence + description: Include redacted logs/screenshots/recordings that prove the behavior. + render: shell + - type: textarea + id: impact + attributes: + label: Impact and severity + description: | + Explain who is affected, how severe it is, how often it happens, and the practical consequence. + Include: + - Affected users/systems/channels + - Severity (annoying, blocks workflow, data risk, etc.) + - Frequency (always/intermittent/edge case) + - Consequence (missed messages, failed onboarding, extra cost, etc.) + placeholder: | + Affected: Telegram group users on 2026.2.13 + Severity: High (blocks replies) + Frequency: 100% repro + Consequence: Agents cannot respond in threads + - type: textarea + id: additional_information + attributes: + label: Additional information + description: Add any context that helps triage but does not fit above. + placeholder: Regression started after upgrade from 2026.2.12; temporary workaround is restarting gateway every 30m. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index 7b33641dc1..0000000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -name: Feature request -about: Suggest an idea or improvement for Clawdbot. -title: "[Feature]: " -labels: enhancement ---- - -## Summary - -Describe the problem you are trying to solve or the opportunity you see. - -## Proposed solution - -What would you like Clawdbot to do? - -## Alternatives considered - -Any other approaches you have considered? - -## Additional context - -Links, screenshots, or related issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000000..3594b73a2c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,70 @@ +name: Feature request +description: Propose a new capability or product improvement. +title: "[Feature]: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Help us evaluate this request with concrete use cases and tradeoffs. + - type: textarea + id: summary + attributes: + label: Summary + description: One-line statement of the requested capability. + placeholder: Add per-channel default response prefix. + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem to solve + description: What user pain this solves and why current behavior is insufficient. + placeholder: Teams cannot distinguish agent personas in mixed channels, causing misrouted follow-ups. + validations: + required: true + - type: textarea + id: proposed_solution + attributes: + label: Proposed solution + description: Desired behavior/API/UX with as much specificity as possible. + placeholder: Support channels..responsePrefix with default fallback and account-level override. + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches considered and why they are weaker. + placeholder: Manual prefixing in prompts is inconsistent and hard to enforce. + - type: textarea + id: impact + attributes: + label: Impact + description: | + Explain who is affected, severity/urgency, how often this pain occurs, and practical consequences. + Include: + - Affected users/systems/channels + - Severity (annoying, blocks workflow, etc.) + - Frequency (always/intermittent/edge case) + - Consequence (delays, errors, extra manual work, etc.) + placeholder: | + Affected: Multi-team shared channels + Severity: Medium + Frequency: Daily + Consequence: +20 minutes/day/operator and delayed alerts + validations: + required: true + - type: textarea + id: evidence + attributes: + label: Evidence/examples + description: Prior art, links, screenshots, logs, or metrics. + placeholder: Comparable behavior in X, sample config, and screenshot of current limitation. + - type: textarea + id: additional_information + attributes: + label: Additional information + description: Extra context, constraints, or references not covered above. + placeholder: Must remain backward-compatible with existing config keys. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000..9b0e7f8dc4 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,108 @@ +## Summary + +Describe the problem and fix in 2–5 bullets: + +- Problem: +- Why it matters: +- What changed: +- What did NOT change (scope boundary): + +## Change Type (select all) + +- [ ] Bug fix +- [ ] Feature +- [ ] Refactor +- [ ] Docs +- [ ] Security hardening +- [ ] Chore/infra + +## Scope (select all touched areas) + +- [ ] Gateway / orchestration +- [ ] Skills / tool execution +- [ ] Auth / tokens +- [ ] Memory / storage +- [ ] Integrations +- [ ] API / contracts +- [ ] UI / DX +- [ ] CI/CD / infra + +## Linked Issue/PR + +- Closes # +- Related # + +## User-visible / Behavior Changes + +List user-visible changes (including defaults/config). +If none, write `None`. + +## Security Impact (required) + +- New permissions/capabilities? (`Yes/No`) +- Secrets/tokens handling changed? (`Yes/No`) +- New/changed network calls? (`Yes/No`) +- Command/tool execution surface changed? (`Yes/No`) +- Data access scope changed? (`Yes/No`) +- If any `Yes`, explain risk + mitigation: + +## Repro + Verification + +### Environment + +- OS: +- Runtime/container: +- Model/provider: +- Integration/channel (if any): +- Relevant config (redacted): + +### Steps + +1. +2. +3. + +### Expected + +- + +### Actual + +- + +## Evidence + +Attach at least one: + +- [ ] Failing test/log before + passing after +- [ ] Trace/log snippets +- [ ] Screenshot/recording +- [ ] Perf numbers (if relevant) + +## Human Verification (required) + +What you personally verified (not just CI), and how: + +- Verified scenarios: +- Edge cases checked: +- What you did **not** verify: + +## Compatibility / Migration + +- Backward compatible? (`Yes/No`) +- Config/env changes? (`Yes/No`) +- Migration needed? (`Yes/No`) +- If yes, exact upgrade steps: + +## Failure Recovery (if this breaks) + +- How to disable/revert this change quickly: +- Files/config to restore: +- Known bad symptoms reviewers should watch for: + +## Risks and Mitigations + +List only real risks for this PR. Add/remove entries as needed. If none, write `None`. + +- Risk: + - Mitigation: diff --git a/AGENTS.md b/AGENTS.md index db9fd04028..8a48c04024 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,8 +100,8 @@ - Create commits with `scripts/committer "" `; avoid manual `git add`/`git commit` so staging stays scoped. - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`). - Group related changes; avoid bundling unrelated refactors. -- Read this when submitting a PR: `docs/help/submitting-a-pr.md` ([Submitting a PR](https://docs.openclaw.ai/help/submitting-a-pr)) -- Read this when submitting an issue: `docs/help/submitting-an-issue.md` ([Submitting an Issue](https://docs.openclaw.ai/help/submitting-an-issue)) +- PR submission template (canonical): `.github/pull_request_template.md` +- Issue submission templates (canonical): `.github/ISSUE_TEMPLATE/` ## Shorthand Commands diff --git a/docs/docs.json b/docs/docs.json index 57205e8d9d..f8f81e6e13 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1290,7 +1290,7 @@ }, { "group": "Contributing", - "pages": ["help/submitting-a-pr", "help/submitting-an-issue", "ci"] + "pages": ["ci"] }, { "group": "Docs meta", @@ -1817,10 +1817,6 @@ "group": "开发者设置", "pages": ["zh-CN/start/setup"] }, - { - "group": "贡献", - "pages": ["zh-CN/help/submitting-a-pr", "zh-CN/help/submitting-an-issue"] - }, { "group": "文档元信息", "pages": ["zh-CN/start/hubs", "zh-CN/start/docs-directory"] diff --git a/docs/help/submitting-a-pr.md b/docs/help/submitting-a-pr.md deleted file mode 100644 index 73b0b69e3a..0000000000 --- a/docs/help/submitting-a-pr.md +++ /dev/null @@ -1,398 +0,0 @@ ---- -summary: "How to submit a high signal PR" -title: "Submitting a PR" ---- - -Good PRs are easy to review: reviewers should quickly know the intent, verify behavior, and land changes safely. This guide covers concise, high-signal submissions for human and LLM review. - -## What makes a good PR - -- [ ] Explain the problem, why it matters, and the change. -- [ ] Keep changes focused. Avoid broad refactors. -- [ ] Summarize user-visible/config/default changes. -- [ ] List test coverage, skips, and reasons. -- [ ] Add evidence: logs, screenshots, or recordings (UI/UX). -- [ ] Code word: put “lobster-biscuit” in the PR description if you read this guide. -- [ ] Run/fix relevant `pnpm` commands before creating PR. -- [ ] Search codebase and GitHub for related functionality/issues/fixes. -- [ ] Base claims on evidence or observation. -- [ ] Good title: verb + scope + outcome (e.g., `Docs: add PR and issue templates`). - -Be concise; concise review > grammar. Omit any non-applicable sections. - -### Baseline validation commands (run/fix failures for your change) - -- `pnpm lint` -- `pnpm check` -- `pnpm build` -- `pnpm test` -- Protocol changes: `pnpm protocol:check` - -## Progressive disclosure - -- Top: summary/intent -- Next: changes/risks -- Next: test/verification -- Last: implementation/evidence - -## Common PR types: specifics - -- [ ] Fix: Add repro, root cause, verification. -- [ ] Feature: Add use cases, behavior/demos/screenshots (UI). -- [ ] Refactor: State "no behavior change", list what moved/simplified. -- [ ] Chore: State why (e.g., build time, CI, dependencies). -- [ ] Docs: Before/after context, link updated page, run `pnpm format`. -- [ ] Test: What gap is covered; how it prevents regressions. -- [ ] Perf: Add before/after metrics, and how measured. -- [ ] UX/UI: Screenshots/video, note accessibility impact. -- [ ] Infra/Build: Environments/validation. -- [ ] Security: Summarize risk, repro, verification, no sensitive data. Grounded claims only. - -## Checklist - -- [ ] Clear problem/intent -- [ ] Focused scope -- [ ] List behavior changes -- [ ] List and result of tests -- [ ] Manual test steps (when applicable) -- [ ] No secrets/private data -- [ ] Evidence-based - -## General PR Template - -```md -#### Summary - -#### Behavior Changes - -#### Codebase and GitHub Search - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort (self-reported): -- Agent notes (optional, cite evidence): -``` - -## PR Type templates (replace with your type) - -### Fix - -```md -#### Summary - -#### Repro Steps - -#### Root Cause - -#### Behavior Changes - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Feature - -```md -#### Summary - -#### Use Cases - -#### Behavior Changes - -#### Existing Functionality Check - -- [ ] I searched the codebase for existing functionality. - Searches performed (1-3 bullets): - - - - - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Refactor - -```md -#### Summary - -#### Scope - -#### No Behavior Change Statement - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Chore/Maintenance - -```md -#### Summary - -#### Why This Matters - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Docs - -```md -#### Summary - -#### Pages Updated - -#### Before/After - -#### Formatting - -pnpm format - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Test - -```md -#### Summary - -#### Gap Covered - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Perf - -```md -#### Summary - -#### Baseline - -#### After - -#### Measurement Method - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### UX/UI - -```md -#### Summary - -#### Screenshots or Video - -#### Accessibility Impact - -#### Tests - -#### Manual Testing - -### Prerequisites - -- - -### Steps - -1. -2. **Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Infra/Build - -```md -#### Summary - -#### Environments Affected - -#### Validation Steps - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` - -### Security - -```md -#### Summary - -#### Risk Summary - -#### Repro Steps - -#### Mitigation or Fix - -#### Verification - -#### Tests - -#### Manual Testing (omit if N/A) - -### Prerequisites - -- - -### Steps - -1. -2. - -#### Evidence (omit if N/A) - -**Sign-Off** - -- Models used: -- Submitter effort: -- Agent notes: -``` diff --git a/docs/help/submitting-an-issue.md b/docs/help/submitting-an-issue.md deleted file mode 100644 index 5aa8444455..0000000000 --- a/docs/help/submitting-an-issue.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -summary: "Filing high-signal issues and bug reports" -title: "Submitting an Issue" ---- - -## Submitting an Issue - -Clear, concise issues speed up diagnosis and fixes. Include the following for bugs, regressions, or feature gaps: - -### What to include - -- [ ] Title: area & symptom -- [ ] Minimal repro steps -- [ ] Expected vs actual -- [ ] Impact & severity -- [ ] Environment: OS, runtime, versions, config -- [ ] Evidence: redacted logs, screenshots (non-PII) -- [ ] Scope: new, regression, or longstanding -- [ ] Code word: lobster-biscuit in your issue -- [ ] Searched codebase & GitHub for existing issue -- [ ] Confirmed not recently fixed/addressed (esp. security) -- [ ] Claims backed by evidence or repro - -Be brief. Terseness > perfect grammar. - -Validation (run/fix before PR): - -- `pnpm lint` -- `pnpm check` -- `pnpm build` -- `pnpm test` -- If protocol code: `pnpm protocol:check` - -### Templates - -#### Bug report - -```md -- [ ] Minimal repro -- [ ] Expected vs actual -- [ ] Environment -- [ ] Affected channels, where not seen -- [ ] Logs/screenshots (redacted) -- [ ] Impact/severity -- [ ] Workarounds - -### Summary - -### Repro Steps - -### Expected - -### Actual - -### Environment - -### Logs/Evidence - -### Impact - -### Workarounds -``` - -#### Security issue - -```md -### Summary - -### Impact - -### Versions - -### Repro Steps (safe to share) - -### Mitigation/workaround - -### Evidence (redacted) -``` - -_Avoid secrets/exploit details in public. For sensitive issues, minimize detail and request private disclosure._ - -#### Regression report - -```md -### Summary - -### Last Known Good - -### First Known Bad - -### Repro Steps - -### Expected - -### Actual - -### Environment - -### Logs/Evidence - -### Impact -``` - -#### Feature request - -```md -### Summary - -### Problem - -### Proposed Solution - -### Alternatives - -### Impact - -### Evidence/examples -``` - -#### Enhancement - -```md -### Summary - -### Current vs Desired Behavior - -### Rationale - -### Alternatives - -### Evidence/examples -``` - -#### Investigation - -```md -### Summary - -### Symptoms - -### What Was Tried - -### Environment - -### Logs/Evidence - -### Impact -``` - -### Submitting a fix PR - -Issue before PR is optional. Include details in PR if skipping. Keep the PR focused, note issue number, add tests or explain absence, document behavior changes/risks, include redacted logs/screenshots as proof, and run proper validation before submitting. diff --git a/docs/zh-CN/help/submitting-a-pr.md b/docs/zh-CN/help/submitting-a-pr.md deleted file mode 100644 index b2feee4dc0..0000000000 --- a/docs/zh-CN/help/submitting-a-pr.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -summary: 如何提交高信号 PR -title: 提交 PR ---- - -# 提交 PR - -该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting a PR](/help/submitting-a-pr)。 diff --git a/docs/zh-CN/help/submitting-an-issue.md b/docs/zh-CN/help/submitting-an-issue.md deleted file mode 100644 index c328002a71..0000000000 --- a/docs/zh-CN/help/submitting-an-issue.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -summary: 如何提交高信号 Issue -title: 提交 Issue ---- - -# 提交 Issue - -该页面是英文文档的中文占位版本，完整内容请先参考英文版：[Submitting an Issue](/help/submitting-an-issue)。