Docs: revise PR and issue submission guides (#10617)

* Docs: revise PR submission guide

* Docs: revise issue submission guide
This commit is contained in:
Tak Hoffman
2026-02-06 13:29:11 -06:00
committed by GitHub
parent 4216449405
commit e3d3893d5d
2 changed files with 317 additions and 217 deletions

View File

@@ -3,283 +3,396 @@ 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.
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
- [ ] 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`).
- [ ] 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`).
Guideline: concision > grammar. Be terse if it makes review faster.
Be concise; concise review > grammar. Omit any non-applicable sections.
Baseline validation commands (run as appropriate for the change, and fix failures before submitting):
### Baseline validation commands (run/fix failures for your change):
- `pnpm lint`
- `pnpm check`
- `pnpm build`
- `pnpm test`
- If you touch protocol code: `pnpm protocol:check`
- Protocol changes: `pnpm protocol:check`
## Progressive disclosure
Use a short top section, then deeper details as needed.
- Top: summary/intent
- Next: changes/risks
- Next: test/verification
- Last: implementation/evidence
1. Summary and intent
2. Behavior changes and risks
3. Tests and verification
4. Implementation details and evidence
## Common PR types: specifics
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.
- [ ] 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
- [ ] 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.
- [ ] Clear problem/intent
- [ ] Focused scope
- [ ] List behavior changes
- [ ] List and result of tests
- [ ] Manual test steps (when applicable)
- [ ] No secrets/private data
- [ ] Evidence-based
## Template
## General PR Template
```md
## Summary
#### Summary
## Behavior Changes
#### Behavior Changes
## Codebase and GitHub Search
#### Codebase and GitHub Search
## Tests
#### Tests
## Evidence
#### Manual Testing (omit if N/A)
## Sign-Off
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort (self-reported):
- Agent notes (optional, cite evidence):
```
## Templates by PR type
## PR Type templates (replace with your type)
### Fix
```md
## Summary
#### Summary
## Repro Steps
#### Repro Steps
## Root Cause
#### Root Cause
## Behavior Changes
#### Behavior Changes
## Tests
#### Tests
## Evidence
#### Manual Testing (omit if N/A)
## Sign-Off
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Feature
```md
## Summary
#### Summary
## Use Cases
#### Use Cases
## Behavior Changes
#### Behavior Changes
## Existing Functionality Check
#### Existing Functionality Check
- [ ] I searched the codebase for existing functionality before implementing this.
- [ ] I searched the codebase for existing functionality.
Searches performed (1-3 bullets):
-
-
Searches performed (1-3 bullets, one sentence each):
#### Tests
#### Manual Testing (omit if N/A)
### Prerequisites
-
-
## Tests
### Steps
## Evidence
1.
2.
## Sign-Off
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Refactor
```md
## Summary
#### Summary
## Scope
#### Scope
## No Behavior Change Statement
#### No Behavior Change Statement
## Tests
#### Tests
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Chore/Maintenance
```md
## Summary
#### Summary
## Why This Matters
#### Why This Matters
## Tests
#### Tests
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Docs
```md
## Summary
#### Summary
## Pages Updated
#### Pages Updated
## Screenshots or Before/After
#### Before/After
## Formatting
#### Formatting
pnpm format
## Sign-Off
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Test
```md
## Summary
#### Summary
## Gap Covered
#### Gap Covered
## Tests
#### Tests
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Perf
```md
## Summary
#### Summary
## Baseline
#### Baseline
## After
#### After
## Measurement Method
#### Measurement Method
## Tests
#### Tests
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### UX/UI
```md
## Summary
#### Summary
## Screenshots or Video
#### Screenshots or Video
## Accessibility Impact
#### Accessibility Impact
## Tests
#### Tests
## Sign-Off
#### Manual Testing
### Prerequisites
-
### Steps
1.
2. **Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Infra/Build
```md
## Summary
#### Summary
## Environments Affected
#### Environments Affected
## Validation Steps
#### Validation Steps
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```
### Security
```md
## Summary
#### Summary
## Risk Summary
#### Risk Summary
## Repro Steps
#### Repro Steps
## Mitigation or Fix
#### Mitigation or Fix
## Verification
#### Verification
## Tests
#### Tests
## Sign-Off
#### Manual Testing (omit if N/A)
### Prerequisites
-
### Steps
1.
2.
#### Evidence (omit if N/A)
**Sign-Off**
- Models used:
- Submitter effort summary (self-reported, subjective):
- Agent notes (optional; brief; cite evidence):
- Submitter effort:
- Agent notes:
```

View File

@@ -1,165 +1,152 @@
---
summary: "How to file high signal issues and bug reports"
summary: "Filing high-signal issues and bug reports"
title: "Submitting an Issue"
---
# 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.
Clear, concise issues speed up diagnosis and fixes. Include the following for bugs, regressions, or feature gaps:
## What makes a good issue
### What to include
- [ ] 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.
- [ ] 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
Guideline: concision > grammar. Be terse if it makes review faster.
Be brief. Terseness > perfect grammar.
Baseline validation commands (run as appropriate for the change, and fix failures before submitting a PR):
Validation (run/fix before PR):
- `pnpm lint`
- `pnpm check`
- `pnpm build`
- `pnpm test`
- If you touch protocol code: `pnpm protocol:check`
- If protocol code: `pnpm protocol:check`
## Templates
### Templates
### Bug report
#### Bug report
```md
## Bug report checklist
- [ ] Minimal repro steps
- [ ] Minimal repro
- [ ] 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
- [ ] Environment
- [ ] Affected channels, where not seen
- [ ] Logs/screenshots (redacted)
- [ ] Impact/severity
- [ ] Workarounds
## Summary
### Summary
## Repro Steps
### Repro Steps
## Expected
### Expected
## Actual
### Actual
## Environment
### Environment
## Logs or Evidence
### Logs/Evidence
## Impact
### Impact
## Workarounds
### Workarounds
```
### Security issue
#### Security issue
```md
## Summary
### Summary
## Impact
### Impact
## Affected Versions
### Versions
## Repro Steps (if safe to share)
### Repro Steps (safe to share)
## Mitigation or Workaround
### Mitigation/workaround
## Evidence (redacted)
### 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.
_Avoid secrets/exploit details in public. For sensitive issues, minimize detail and request private disclosure._
### Regression report
#### Regression report
```md
## Summary
### Summary
## Last Known Good
### Last Known Good
## First Known Bad
### First Known Bad
## Repro Steps
### Repro Steps
## Expected
### Expected
## Actual
### Actual
## Environment
### Environment
## Logs or Evidence
### Logs/Evidence
## Impact
### Impact
```
### Feature request
#### Feature request
```md
## Summary
### Summary
## Problem
### Problem
## Proposed Solution
### Proposed Solution
## Alternatives Considered
### Alternatives
## Impact
### Impact
## Evidence or Examples
### Evidence/examples
```
### Enhancement request
#### Enhancement
```md
## Summary
### Summary
## Current Behavior
### Current vs Desired Behavior
## Desired Behavior
### Rationale
## Why This Matters
### Alternatives
## Alternatives Considered
## Evidence or Examples
### Evidence/examples
```
### Investigation request
#### Investigation
```md
## Summary
### Summary
## Symptoms
### Symptoms
## What Was Tried
### What Was Tried
## Environment
### Environment
## Logs or Evidence
### Logs/Evidence
## Impact
### Impact
```
## If you are submitting a fix PR
### 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.
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.