From d7ac6b5bca2e92117893dcc31ad635dd87ad8ee6 Mon Sep 17 00:00:00 2001 From: Tunglies <77394545+Tunglies@users.noreply.github.com> Date: Mon, 16 Nov 2026 23:39:20 +0800 Subject: [PATCH] chore(docs): centralize issue guidance and trim PR descriptions --- .github/AGENTS.md | 31 ++++++++++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 30 ++++++++++++++++++++++++- .github/workflows/docs-consistency.yml | 7 ++++-- AGENTS.md | 16 ++++--------- CONTRIBUTING.md | 7 +++--- 5 files changed, 73 insertions(+), 18 deletions(-) create mode 100644 .github/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 000000000..2815d67eb --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,31 @@ +# Issue and PR Guidelines + +These rules apply to Issue and PR work, including operations through `gh` or an +API. The root [AGENTS.md](../AGENTS.md) defines the repository-wide contract. + +## Issues + +When creating, drafting, triaging, splitting, or implementing from a community +issue, follow [ISSUE_GUIDELINES.md](ISSUE_GUIDELINES.md). Do not create or modify +GitHub issues without explicit authorization. + +## PR Descriptions + +When creating or updating a PR body, follow the +[PR template](PULL_REQUEST_TEMPLATE.md). Describe the final change; replace stale +text instead of appending work history. Omit routine check-pass declarations, +including Clippy, lint, and local tests. Keep only evidence and limitations that +help reviewers assess the change; the template defines what belongs in the body +and when Scope is needed. + +Before publishing or updating a PR body, remove repetition, self-evaluation, and +details already clear from the diff. Keep only sentences that help review the +change. + +## AI Disclosure + +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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5137b940b..73c24216d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,29 @@ + + ## Problem What breaks or what is missing. Product bug fixes and features require a @@ -14,4 +40,6 @@ Why this change solves the problem — the reasoning behind the approach, not a ## Scope -What changed. If anything outside the core fix was touched, explain why it was necessary. New tests are not expected by default — if any were added, justify why each is needed. +Optional: explain necessary changes outside the core fix, PR dependencies, or +why added tests are needed. Otherwise remove this section. New tests are not +expected by default. diff --git a/.github/workflows/docs-consistency.yml b/.github/workflows/docs-consistency.yml index eb9f7a6c7..cb4815437 100644 --- a/.github/workflows/docs-consistency.yml +++ b/.github/workflows/docs-consistency.yml @@ -12,6 +12,7 @@ on: - REVIEW.md - src/AGENTS.md - src-tauri/AGENTS.md + - .github/AGENTS.md - .github/ISSUE_GUIDELINES.md - .github/agents/agentic-workflows.md - .github/skills/agentic-workflows/SKILL.md @@ -30,6 +31,7 @@ on: - REVIEW.md - src/AGENTS.md - src-tauri/AGENTS.md + - .github/AGENTS.md - .github/ISSUE_GUIDELINES.md - .github/agents/agentic-workflows.md - .github/skills/agentic-workflows/SKILL.md @@ -57,7 +59,8 @@ jobs: check AGENTS.md 'Issue first' check AGENTS.md 'Author accountability' check AGENTS.md 'pr-ai-slop-review' - check AGENTS.md 'Disclose AI automation' + check AGENTS.md '(.github/AGENTS.md)' + check .github/AGENTS.md '## AI Disclosure' check CONTRIBUTING.md 'Assisted by:' check .github/workflows/pr-ai-slop-review.md '(../../CONTRIBUTING.md)' check .github/workflows/pr-ai-slop-review.md '(../../AGENTS.md)' @@ -84,7 +87,7 @@ jobs: sources = [ "AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md", - "src/AGENTS.md", "src-tauri/AGENTS.md", ".github/ISSUE_GUIDELINES.md", + "src/AGENTS.md", "src-tauri/AGENTS.md", ".github/AGENTS.md", ".github/ISSUE_GUIDELINES.md", ".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md", ".github/workflows/pr-verify-fix.md", ".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md", diff --git a/AGENTS.md b/AGENTS.md index 6211b6c63..e64505af7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,16 +48,11 @@ the ownership evidence the AI-slop review evaluates (see 8. **Minimal diffs.** Match the surrounding code's style, naming, and comment density. Do not introduce new dependencies or restructure working code unless 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.** Agentic workflow Markdown, including the +9. **Compiled workflows.** Agentic workflow Markdown, including the [AI-slop policy](.github/workflows/pr-ai-slop-review.md) and shared imports, is compiled: after editing it, run `gh aw compile` and commit the affected `.lock.yml` files. Never edit lock files directly. -11. **Changelog.** Entries follow the rules in +10. **Changelog.** Entries follow the rules in [`template/Changelog.md`](template/Changelog.md): one line per user-visible change, no internals. @@ -78,8 +73,5 @@ the ownership evidence the AI-slop review evaluates (see ## Issue and PR Workflows -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. +For Issue and PR work, read [`.github/AGENTS.md`](.github/AGENTS.md), including +when using `gh` or an API without editing files under `.github/`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 32df1f29e..152f6f95a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -168,9 +168,10 @@ to run every command for every change. Run commands from the repository root. Tie results to the code reviewed: identify the base/head commits for branch comparisons and include task-relevant staged, unstaged, and untracked files in a -local review. Report -the command or interaction, observed result, and material gaps in the existing -conversation or PR; no separate verification report is required. Static checks, +local review. Keep command-level results in the working conversation. For PR +descriptions, follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md): include +behavioral evidence and material gaps relevant to review, omitting routine check +pass lists. No separate verification report is required. Static checks, mocks, browser previews, native runs, and remote CI establish different things. When code changes after verification, repeat affected checks. Attribute a failure to the baseline only after comparing the same check on the base revision.