From 02bd739ab68ceecb9637ecce006dc10bc5704655 Mon Sep 17 00:00:00 2001 From: Tunglies <77394545+Tunglies@users.noreply.github.com> Date: Wed, 21 Oct 2026 19:21:08 +0800 Subject: [PATCH] docs: clarify issue and PR intake rules --- .github/ISSUE_GUIDELINES.md | 33 ++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 4 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 4 ++ .github/PULL_REQUEST_TEMPLATE.md | 8 +++- AGENTS.md | 46 ++++++++++++---------- 5 files changed, 73 insertions(+), 22 deletions(-) create mode 100644 .github/ISSUE_GUIDELINES.md diff --git a/.github/ISSUE_GUIDELINES.md b/.github/ISSUE_GUIDELINES.md new file mode 100644 index 000000000..d1740006c --- /dev/null +++ b/.github/ISSUE_GUIDELINES.md @@ -0,0 +1,33 @@ +# Issue Guidelines / Issue 提交指引 + +Use these suggestions to make reports easier to assess. State what you observed +and what you could not verify; unknown details are fine. + +以下建议有助于维护者评估问题。请说明实际观察到的现象和无法确认的部分；未知信息可以留空。 + +- Search existing issues by symptom, conditions, and outcome. Add new evidence + to an existing report when it describes the same problem. + 按现象、条件和结果搜索已有 Issue。若描述的是同一问题，请在原 Issue 中补充新证据。 +- Keep each issue to one distinct user problem or requested outcome. Split + unrelated findings instead of bundling an audit or checklist. + 每个 Issue 聚焦一个独立的问题或需求结果；无关发现请拆开，不要把审计清单打包成一个 Issue。 +- For bugs, include the version, operating system, steps, and actual versus + expected behavior when known. A root-cause diagnosis is not required. Share + only relevant logs and redact tokens or personal information. + 反馈 Bug 时，尽可能提供版本、操作系统、复现步骤及实际与预期行为。无需先判断根因；只提供相关日志，并遮盖令牌和个人信息。 +- For feature requests, describe the user task, current limitation, desired + outcome, and affected platforms. An implementation proposal is optional. + 提交功能请求时，请描述用户要完成的任务、当前限制、期望结果和适用平台；实现方案不是必填项。 +- Separate observations from guesses. An AI or scanner finding is a hypothesis + until its affected configuration, concrete impact, and supporting evidence + are stated; do not present a list of theoretical risks as confirmed bugs. + 区分观察结果和推测。AI 或扫描器的发现应先视为假设；请说明受影响的配置、具体影响和支持证据，不要把理论风险清单写成已确认的 Bug。 +- Do not post secrets, personal data, or sensitive exploit details in a public + issue. Ask maintainers how to share sensitive security information safely. + 请勿在公开 Issue 中发布密钥、个人信息或敏感利用细节；如涉及安全敏感信息，请先询问维护者如何安全提供。 +- AI assistance is welcome; human contributors do not need to disclose it. If + an AI agent or automation creates or co-authors an issue, add a final body line + such as `Assisted by: GPT-5.6 High`. Omit effort when the runtime does not + report it. Disclosure is transparency only, not evidence for or against issue + quality. + 欢迎使用 AI 辅助，人工提交者无需披露。如果 Issue 由 AI Agent 或自动化创建或共同撰写，请在正文末尾添加披露行，例如 `Assisted by: GPT-5.6 High`。运行环境未提供 effort 时可省略。披露仅用于提高透明度，不作为 Issue 质量的正面或负面证据。 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index ebce301f4..876cdd09c 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -10,6 +10,8 @@ body: value: | ## 在提交问题之前，请确认以下事项： + 提交前可参考 [Issue 提交指引](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/.github/ISSUE_GUIDELINES.md)，说明可观察到的问题和证据；不确定的原因请标为猜测。 + 1. 请 **确保** 您已经查阅了 [Clash Verge Rev 官方文档](https://clash-verge-rev.github.io/guide/term.html) 以及 [常见问题](https://clash-verge-rev.github.io/faq/windows.html) 2. 请 **确保** [已有的问题](https://github.com/clash-verge-rev/clash-verge-rev/issues?q=is%3Aissue) 中没有人提交过相似 issue，否则请在已有的 issue 下进行讨论 3. 请 **务必** 给 issue 填写一个简洁明了的标题，以便他人快速检索 @@ -19,6 +21,8 @@ body: ## Before submitting the issue, please make sure of the following checklist: + See the [Issue guidelines](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/.github/ISSUE_GUIDELINES.md) for how to describe observed behavior and evidence; mark uncertain causes as hypotheses. + 1. Please make sure you have read the [Clash Verge Rev official documentation](https://clash-verge-rev.github.io/guide/term.html) and [FAQ](https://clash-verge-rev.github.io/faq/windows.html) 2. Please make sure there is no similar issue in the [existing issues](https://github.com/clash-verge-rev/clash-verge-rev/issues?q=is%3Aissue), otherwise please discuss under the existing issue 3. Please be sure to fill in a concise and clear title for the issue so that others can quickly search diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index d30728a51..1ef2780ca 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -9,12 +9,16 @@ body: attributes: value: | ## 在提交问题之前，请确认以下事项： + 可参考 [Issue 提交指引](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/.github/ISSUE_GUIDELINES.md)，描述用户任务、当前限制和期望结果。 + 1. 请 **确保** 您已经查阅了 [Clash Verge Rev 官方文档](https://clash-verge-rev.github.io/guide/term.html) 确认软件不存在类似的功能 2. 请 **确保** [已有的问题](https://github.com/clash-verge-rev/clash-verge-rev/issues?q=is%3Aissue) 中没有人提交过相似 issue，否则请在已有的 issue 下进行讨论 3. 请 **务必** 给issue填写一个简洁明了的标题，以便他人快速检索 4. 请 **务必** 先下载 [AutoBuild](https://github.com/clash-verge-rev/clash-verge-rev/releases/tag/autobuild) 版本测试，确保该功能还未实现 5. 请 **务必** 按照模板规范详细描述问题，否则 issue 将会被关闭 ## Before submitting the issue, please make sure of the following checklist: + See the [Issue guidelines](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/.github/ISSUE_GUIDELINES.md) for describing the user task, current limitation, and desired outcome. + 1. Please make sure you have read the [Clash Verge Rev official documentation](https://clash-verge-rev.github.io/guide/term.html) to confirm that the software does not have similar functions 2. Please make sure there is no similar issue in the [existing issues](https://github.com/clash-verge-rev/clash-verge-rev/issues?q=is%3Aissue), otherwise please discuss under the existing issue 3. Please be sure to fill in a concise and clear title for the issue so that others can quickly search diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9d3da294d..5137b940b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,12 @@ ## Problem -What breaks or what is missing. Link the issue if one exists (`Fixes #123`). +What breaks or what is missing. Product bug fixes and features require a +pre-existing issue; link it here (`Fixes #123` only when this PR fully resolves +it). Maintenance work (such as chore, perf, docs, refactor, test, CI/build, +dependency, style, routine localization, or release changes) does not require +an issue link; link one when it defines the scope. For reverts, link the PR or +commit being reverted. For security-sensitive fixes that cannot be tracked +publicly, follow maintainer-approved private tracking. ## Approach diff --git a/AGENTS.md b/AGENTS.md index ce9822479..d6ec809a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,22 +18,25 @@ These rules apply to every change, whether human- or agent-authored. They match the ownership evidence the AI-slop review evaluates (see [`pr-ai-slop-review.md`](.github/workflows/pr-ai-slop-review.md)). -1. **Issue first.** Non-trivial changes require a pre-existing issue describing - the problem. If none exists, ask the maintainers to open or approve one - before implementing. +1. **Issue first.** Product bug fixes and features require a pre-existing issue; + self-scoped maintenance work does not. Follow the PR template for linkage and + revert references. If a required issue is missing, ask maintainers to open or + approve one before implementing. For security-sensitive fixes that cannot be + tracked publicly, follow maintainer-approved private tracking. 2. **Scope discipline.** Every changed file must be justifiable from the linked - issue. No drive-by refactors, renames, formatting churn, or dependency bumps - unrelated to the problem being fixed. + issue or the stated PR scope. No drive-by refactors, renames, formatting + churn, or dependency bumps unrelated to the work. 3. **Author accountability.** AI assistance is welcome, but the contributor owns the result: understand the change, describe the problem and approach in your own words, and verify the change against the reported behavior before submitting. 4. **Tests are justified, not default.** Do not add tests, test scaffolding, or - speculative defensive code unless the linked issue demands them. When a test - is genuinely necessary — it reproduces the reported regression or guards - behavior whose breakage would otherwise go unnoticed — keep it minimal and - state in the PR body why it is needed. Bulk test files and defensive - programming for hypothetical failure modes are PR bloat, not rigor. + speculative defensive code unless the linked issue or stated task demands + them. When a test is genuinely necessary — it reproduces the reported + regression or guards behavior whose breakage would otherwise go unnoticed — + keep it minimal and state in the PR body why it is needed. Bulk test files + and defensive programming for hypothetical failure modes are PR bloat, not + rigor. 5. **Comments state constraints, not narration.** Write a comment only for a non-obvious constraint the code cannot express; never restate what the code does. @@ -44,13 +47,12 @@ the ownership evidence the AI-slop review evaluates (see real evidence instead: reproduction steps, failure output, targeted tests. 8. **Minimal diffs.** Match the surrounding code's style, naming, and comment density. Do not introduce new dependencies or restructure working code unless - the issue demands it. -9. **Disclose AI automation.** When an agent produces or co-produces a change, - append a footer line to the PR body with the model and effort used (e.g. - `Assisted by: GPT-5.6 High`). The PR template intentionally omits this line — - the agent adds it itself, humans are not asked to declare anything. Effort may - be omitted when the runtime does not report it. Disclosure is transparency - only; it does not substitute for any rule above. + the linked issue or stated task demands it. +9. **Disclose AI automation.** When an agent creates or co-creates a PR or Issue, + append a final body line with the model and effort used (e.g. + `Assisted by: GPT-5.6 High`). Effort may be omitted when the runtime does not + report it. Human contributors are not asked to disclose AI assistance. + Disclosure is transparency only and carries no positive or negative weight. 10. **Compiled workflows.** The AI-slop review policy in [pr-ai-slop-review.md](.github/workflows/pr-ai-slop-review.md) is compiled: after editing it, run `gh aw compile` and commit the regenerated @@ -59,8 +61,10 @@ the ownership evidence the AI-slop review evaluates (see [`template/Changelog.md`](template/Changelog.md): one line per user-visible change, no internals. -## Pull Request Shape +## Issue and PR Workflows -Describe three things, briefly: the problem (with issue link), why this approach -solves it, and what changed. See -[`PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md). +When drafting, triaging, splitting, or implementing from a community issue, use +the conditional checklist in [`.github/ISSUE_GUIDELINES.md`](.github/ISSUE_GUIDELINES.md). +Do not make GitHub issue changes without explicit authorization. For PRs, follow +the directly loaded [PR template](.github/PULL_REQUEST_TEMPLATE.md); do not +duplicate its prompts here.