From 69b850960225a59fa9a957c530e489ba2a816830 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Wed, 14 Oct 2026 16:07:32 +0800 Subject: [PATCH] docs(contributing): strengthen issue evidence guidance (#3287) --- .github/ISSUE_TEMPLATE/bug_report.yml | 36 +++++++++++++------- .github/ISSUE_TEMPLATE/design_discussion.yml | 2 +- .github/ISSUE_TEMPLATE/documentation.yml | 15 ++++++-- .github/ISSUE_TEMPLATE/feature_request.yml | 6 ++-- AGENTS.md | 11 ++++++ CONTRIBUTING.md | 21 ++++++++++++ 6 files changed, 72 insertions(+), 19 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index f93e9f7bd9..b742aff5f4 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,5 +1,5 @@ name: Bug report -description: Report a reproducible problem in REA +description: Report a problem in REA with observations or source evidence title: "[Bug] " labels: - bug @@ -8,8 +8,12 @@ body: - type: markdown attributes: value: | - Please report one primary behavior per issue. Keep observed behavior - separate from suspected causes, and remove credentials and private paths. + Report one primary behavior per issue. Keep answers concise and grounded + in available evidence. Distinguish observed behavior, source-derived + reasoning, and suspected causes; do not claim a reproduction you did not run. + If a narrative answer is not known, write `NOT_ENOUGH_INFO` and describe + what is missing. Intermittent failures and clearly labeled source-only + reports are welcome. Do not include credentials or sensitive target data. - type: checkboxes id: before-submitting @@ -42,7 +46,7 @@ body: id: observed-behavior attributes: label: Observed behavior - description: What happened? Include the command, MCP tool, provider, target type, and conditions that matter. + description: Describe the actual result, including the exact command or MCP request, relevant provider/target, and supporting evidence below. Label source-only findings instead of claiming execution. validations: required: true @@ -50,7 +54,7 @@ body: id: reproduction attributes: label: Reproduction - description: Give the smallest realistic command, configuration, input, or event sequence that demonstrates the problem. + description: Give the shortest steps you actually ran, with the relevant input or configuration. State how often they reproduced the problem when known. If reproduction is unavailable, say so and provide the observations or source reference you have. placeholder: | 1. Configure or start ... 2. Run ... @@ -62,7 +66,7 @@ body: id: expected-behavior attributes: label: Expected behavior - description: What result, contract, invariant, recovery action, or state transition should have occurred? + description: State the expected result, contract, or recovery action. Cite documentation, source, or a known-good version when available; mark an unverified expectation or unknown reference clearly. validations: required: true @@ -70,7 +74,7 @@ body: id: impact-scope attributes: label: Impact and scope - description: What is affected, what is not affected, and does this affect evidence integrity, process isolation, compatibility, or recovery? + description: Describe observed impact and frequency, including effects on evidence integrity, process isolation, compatibility, or recovery when known. Leave untested scope and severity unknown rather than guessing. validations: required: true @@ -79,7 +83,7 @@ body: attributes: label: REA version description: Use `rea --version` or provide the source revision. - placeholder: 3.1.0 or git revision + placeholder: Exact rea --version output or source commit SHA validations: required: true @@ -116,7 +120,7 @@ body: id: failure-stage attributes: label: Earliest failure stage - description: Select where the incorrect behavior first becomes observable. + description: Select where the incorrect behavior first becomes observable. Choose Unknown if this has not been established. options: - Request parsing or validation - Setup or provider admission @@ -133,8 +137,14 @@ body: id: relevant-evidence attributes: label: Relevant output or evidence - description: Paste the smallest useful CLI output, MCP result, error, trace, or evidence excerpt. Redact sensitive values. - render: text + description: Include the smallest useful output, MCP result, error, screenshot, artifact, or exact source reference. Say how it was obtained and which claim it supports. If unavailable, write NOT_ENOUGH_INFO and explain what is missing. Redact credentials and sensitive target data. + placeholder: | + Command or MCP request actually run: + Relevant result, error, or artifact: + For source-only findings, link the file/revision and relevant code: + Missing evidence or remaining uncertainty: + validations: + required: true - type: textarea id: typed-outcome @@ -146,10 +156,10 @@ body: id: analysis attributes: label: Analysis or suspected cause - description: Optional. Clearly mark source-derived reasoning or a hypothesis; do not present an unverified cause as fact. + description: Optional. Link supporting source and distinguish source-derived reasoning from a hypothesis. A root-cause analysis or proposed fix is not required. - type: textarea id: additional-context attributes: label: Additional context - description: Add links, reduced fixtures, screenshots, or a proposed regression test. + description: Add reduced fixtures, screenshots, or related issues. For observed regressions, include the last known good and first known bad versions when available. Label untested checks as proposals. diff --git a/.github/ISSUE_TEMPLATE/design_discussion.yml b/.github/ISSUE_TEMPLATE/design_discussion.yml index 38d33ac821..28aa67559f 100644 --- a/.github/ISSUE_TEMPLATE/design_discussion.yml +++ b/.github/ISSUE_TEMPLATE/design_discussion.yml @@ -41,7 +41,7 @@ body: id: context-evidence attributes: label: Context and evidence - description: Explain the problem or motivation. If you have evidence, distinguish observed behavior from ideas or guesses. + description: Explain the problem or motivation and link relevant evidence when available. Distinguish observed behavior, source-derived reasoning, proposed behavior, and unknowns. A question without measurements or a finished design is welcome. validations: required: true diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml index fa2bc024ea..a522606a6e 100644 --- a/.github/ISSUE_TEMPLATE/documentation.yml +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -5,6 +5,13 @@ labels: - documentation - triage body: + - type: markdown + attributes: + value: | + Report one documentation problem with the exact location and the smallest + useful supporting passage, example, or result. Keep answers concise. + If something is unknown, write `NOT_ENOUGH_INFO` and explain what is missing. + - type: checkboxes id: before-submitting attributes: @@ -28,7 +35,7 @@ body: id: problem attributes: label: Problem - description: What is unclear, missing, outdated, or incorrect, and who is affected? + description: Quote or describe the current content, explain what is unclear, missing, outdated, or incorrect, and say how to observe the problem. State who is affected when known. validations: required: true @@ -36,7 +43,7 @@ body: id: expected-content attributes: label: Expected content - description: Describe the accurate behavior or example that should be documented. + description: Describe the accurate behavior or example that should be documented, with a reference when available. Label a proposed clarification or unknown behavior clearly. validations: required: true @@ -44,7 +51,9 @@ body: id: evidence attributes: label: Supporting evidence - description: Add source, command output, provider documentation, or a link that supports the correction. + description: Include an exact passage, source reference, command output, provider documentation, or screenshot supporting the report. For missing or unclear guidance, point to the relevant section and explain the gap. If evidence is unavailable, write NOT_ENOUGH_INFO and explain what is missing. + validations: + required: true - type: textarea id: additional-context diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index 4125f3db52..29ed544f21 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -11,6 +11,8 @@ body: Describe one problem and the outcome you would like. Short answers are welcome. Choose "Not sure yet" wherever needed; you do not need code, a finished design, or a complete test plan to propose an idea. + Use concrete examples when available, distinguish current limitations + from proposed behavior, and leave unmeasured impact or unknowns explicit. Read the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Maintainers can help resolve scope and technical questions. Unresolved @@ -58,7 +60,7 @@ body: id: use-cases attributes: label: Use cases - description: Optional additional examples of applications, targets, or callers. Leave blank if covered above. + description: Optional examples of affected workflows, targets, or callers and their practical impact. Include observed frequency or measurements when available; do not invent them. Leave blank if covered above. - type: textarea id: desired-outcome @@ -138,4 +140,4 @@ body: id: references attributes: label: References - description: Link relevant provider documentation, source, measurements, artifacts, issues, or discussions. + description: Optional supporting examples, provider documentation, source, measurements, artifacts, issues, or prior art. Distinguish observed results from expected benefits; an idea without evidence is welcome. diff --git a/AGENTS.md b/AGENTS.md index 48b89c2e39..418ee003c1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,6 +78,17 @@ For test changes or provider claims, use [docs/testing.md](docs/testing.md). Pre Use Conventional Commit subjects and PR titles. Mark breaking changes with `!` or a `BREAKING CHANGE:` footer. Describe behavior changes, relevant validation, and real-provider verification scope. +## Issue Reports + +Follow [issue reporting guidance](CONTRIBUTING.md#reporting-issues) and the matching +issue form. Keep reports concise and cite the smallest useful evidence. +Distinguish observed results, source-derived reasoning, hypotheses, and proposed +checks. Never claim runtime reproduction or measurements you did not perform. +Use `NOT_ENOUGH_INFO` with an explanation for missing narrative answers or evidence. +Incomplete reports, source-only findings, and early feature or design ideas are +welcome when their limitations are explicit; a completed diagnosis or fix is not +required to open an issue. + ## Pull Request Readiness Follow [human ownership and readiness](CONTRIBUTING.md#pull-request-ownership-and-readiness) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7e109c2bf..8f067f7e4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,27 @@ costs change. When adding or changing an MCP tool, follow the [tool design guide](docs/tool-design.md) and preserve the canonical contracts and generated catalog. +## Reporting issues + +Use the issue form that fits the report and keep it concise. For bugs, include +the actual result, the shortest reproduction you ran, the tested version and +environment, and the smallest useful output, artifact, screenshot, or source +reference. Ground expected behavior in documentation, source, or a known-good +version when available. State observed impact and frequency; keep untested scope +and suspected causes explicit. + +Incomplete reports and intermittent failures are welcome. If a narrative answer +or supporting evidence is unavailable, write `NOT_ENOUGH_INFO` and explain the +gap. Clearly label source-only findings and proposed checks; do not claim runtime +reproduction or results you did not observe. A root-cause analysis or fix is not +required to report a problem. Documentation reports should identify the relevant +passage or missing guidance and explain the correction or confusion. + +Feature and design proposals can start with a problem and desired outcome. +Examples, prior art, and measurements help when available; ideas without them +are welcome. Maintainers can investigate reports and help resolve open questions. +Human ownership and readiness declarations apply to PRs as described below. + ## Pull request ownership and readiness AI-assisted contributions are welcome. Every PR must have a human owner who