From e3d3893d5dbec30c2046166b6a71bacfe641ef78 Mon Sep 17 00:00:00 2001 From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com> Date: Fri, 6 Feb 2026 13:29:11 -0600 Subject: [PATCH] Docs: revise PR and issue submission guides (#10617) * Docs: revise PR submission guide * Docs: revise issue submission guide --- docs/help/submitting-a-pr.md | 373 ++++++++++++++++++++----------- docs/help/submitting-an-issue.md | 161 ++++++------- 2 files changed, 317 insertions(+), 217 deletions(-) diff --git a/docs/help/submitting-a-pr.md b/docs/help/submitting-a-pr.md index 3baedc3a1c..caa407a29b 100644 --- a/docs/help/submitting-a-pr.md +++ b/docs/help/submitting-a-pr.md @@ -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: ``` diff --git a/docs/help/submitting-an-issue.md b/docs/help/submitting-an-issue.md index a91a4678bb..5aa8444455 100644 --- a/docs/help/submitting-an-issue.md +++ b/docs/help/submitting-an-issue.md @@ -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.