mirror of
https://github.com/openclaw/openclaw.git
synced 2026-02-08 21:09:23 +08:00
Docs: add PR and issue submission guides (#10150)
* Docs: add PR and issue submission guides * Docs: fix LLM-assisted wording
This commit is contained in:
Tak Hoffman
@@ -95,6 +95,8 @@
|
||||
- Group related changes; avoid bundling unrelated refactors.
|
||||
- Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section.
|
||||
- PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
|
||||
- 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 review flow: when given a PR link, review via `gh pr view`/`gh pr diff` and do **not** change branches.
|
||||
- PR review calls: prefer a single `gh pr view --json ...` to batch metadata/comments; run `gh pr diff` only when needed.
|
||||
- Before starting a review when a GH Issue/PR is pasted: run `git pull`; if there are local changes or unpushed commits, stop and alert the user before reviewing.
|
||||
|
||||
@@ -1230,7 +1230,7 @@
|
||||
},
|
||||
{
|
||||
"group": "Developer workflows",
|
||||
"pages": ["start/setup"]
|
||||
"pages": ["start/setup", "help/submitting-a-pr", "help/submitting-an-issue"]
|
||||
},
|
||||
{
|
||||
"group": "Docs meta",
|
||||
|
||||
214
docs/help/submitting-a-pr.md
Normal file
214
docs/help/submitting-a-pr.md
Normal file
@@ -0,0 +1,214 @@
|
||||
---
|
||||
summary: "How to submit a high signal PR"
|
||||
title: "Submitting a PR"
|
||||
---
|
||||
|
||||
# Submitting a PR
|
||||
|
||||
Good PRs make it easy for reviewers to understand intent, verify behavior, and land changes safely. This guide focuses on high-signal, low-noise submissions that work well with both human review and LLM-assisted review.
|
||||
|
||||
## What makes a good PR
|
||||
|
||||
- [ ] Clear intent: explain the problem, why it matters, and what the change does.
|
||||
- [ ] Tight scope: keep changes focused and avoid drive-by refactors.
|
||||
- [ ] Behavior summary: call out user-visible changes, config changes, and defaults.
|
||||
- [ ] Tests: list what ran, what was skipped, and why.
|
||||
- [ ] Evidence: include logs, screenshots, or short recordings for UI or workflows.
|
||||
- [ ] Code word: include “lobster-biscuit” somewhere in the PR description to confirm you read this guide.
|
||||
- [ ] Baseline checks: run the relevant `pnpm` commands for this repo and fix failures before opening the PR.
|
||||
- [ ] Due diligence: search the codebase for existing functionality and check GitHub for related issues or prior fixes.
|
||||
- [ ] Grounded in reality: claims should be backed by evidence, reproduction, or direct observation.
|
||||
- [ ] Title guidance: use a verb + scope + outcome (for example `Docs: add PR and issue templates`).
|
||||
|
||||
Guideline: concision > grammar. Be terse if it makes review faster.
|
||||
|
||||
Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
|
||||
|
||||
- `pnpm lint`
|
||||
- `pnpm check`
|
||||
- `pnpm build`
|
||||
- `pnpm test`
|
||||
- If you touch protocol code: `pnpm protocol:check`
|
||||
|
||||
## Progressive disclosure
|
||||
|
||||
Use a short top section, then deeper details as needed.
|
||||
|
||||
1. Summary and intent
|
||||
2. Behavior changes and risks
|
||||
3. Tests and verification
|
||||
4. Implementation details and evidence
|
||||
|
||||
This keeps review fast while preserving deep context for anyone who needs it.
|
||||
|
||||
## Common PR types and expectations
|
||||
|
||||
- [ ] Fix: include clear repro, root cause summary, and verification steps.
|
||||
- [ ] Feature: include use cases, behavior changes, and screenshots or demos when UI is involved.
|
||||
- [ ] Refactor: explicitly state “no behavior change” and list what moved or was simplified.
|
||||
- [ ] Chore/Maintenance: note why it matters (build time, CI stability, dependency hygiene).
|
||||
- [ ] Docs: include before/after context and link to the updated page. Run `pnpm format`.
|
||||
- [ ] Test: explain the gap it covers and how it prevents regressions.
|
||||
- [ ] Perf: include baseline and after metrics, plus how they were measured.
|
||||
- [ ] UX/UI: include screenshots or short recordings and any accessibility impact.
|
||||
- [ ] Infra/Build: call out affected environments and how to validate.
|
||||
- [ ] Security: include threat or risk summary, repro steps, and verification plan. Avoid sensitive data in public logs.
|
||||
- [ ] Security: keep reports grounded in reality; avoid speculative claims.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Problem and intent are clear
|
||||
- [ ] Scope is focused
|
||||
- [ ] Behavior changes are listed
|
||||
- [ ] Tests are listed with results
|
||||
- [ ] Evidence is attached when needed
|
||||
- [ ] No secrets or private data
|
||||
- [ ] Grounded in reality: no guesswork or invented context.
|
||||
|
||||
## Template
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Behavior Changes
|
||||
|
||||
## Codebase and GitHub Search
|
||||
|
||||
## Tests
|
||||
|
||||
## Evidence
|
||||
```
|
||||
|
||||
## Templates by PR type
|
||||
|
||||
### Fix
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Repro Steps
|
||||
|
||||
## Root Cause
|
||||
|
||||
## Behavior Changes
|
||||
|
||||
## Tests
|
||||
|
||||
## Evidence
|
||||
```
|
||||
|
||||
### Feature
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Use Cases
|
||||
|
||||
## Behavior Changes
|
||||
|
||||
## Existing Functionality Check
|
||||
|
||||
I searched the codebase for existing functionality before implementing this.
|
||||
|
||||
## Tests
|
||||
|
||||
## Evidence
|
||||
```
|
||||
|
||||
### Refactor
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Scope
|
||||
|
||||
## No Behavior Change Statement
|
||||
|
||||
## Tests
|
||||
```
|
||||
|
||||
### Chore/Maintenance
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Why This Matters
|
||||
|
||||
## Tests
|
||||
```
|
||||
|
||||
### Docs
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Pages Updated
|
||||
|
||||
## Screenshots or Before/After
|
||||
|
||||
## Formatting
|
||||
|
||||
pnpm format
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Gap Covered
|
||||
|
||||
## Tests
|
||||
```
|
||||
|
||||
### Perf
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Baseline
|
||||
|
||||
## After
|
||||
|
||||
## Measurement Method
|
||||
|
||||
## Tests
|
||||
```
|
||||
|
||||
### UX/UI
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Screenshots or Video
|
||||
|
||||
## Accessibility Impact
|
||||
|
||||
## Tests
|
||||
```
|
||||
|
||||
### Infra/Build
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Environments Affected
|
||||
|
||||
## Validation Steps
|
||||
```
|
||||
|
||||
### Security
|
||||
|
||||
```md
|
||||
## Summary
|
||||
|
||||
## Risk Summary
|
||||
|
||||
## Repro Steps
|
||||
|
||||
## Mitigation or Fix
|
||||
|
||||
## Verification
|
||||
|
||||
## Tests
|
||||
```
|
||||
165
docs/help/submitting-an-issue.md
Normal file
165
docs/help/submitting-an-issue.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user