diff --git a/AGENTS.md b/AGENTS.md index 63d90e238..0aa78f1fa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,9 @@ This file provides guidance to AI coding agents (Claude Code, etc.) when working > current, no duplication) and every claim factually true against the current branch (*if you can't grep it on > this branch, don't claim it*). +> **Before opening or updating a pull request, read [`docs/pull-request.md`](docs/pull-request.md)** — this +> repo's PR description structure and evidence rules. + > **Doc map:** [`docs/README.md`](docs/README.md) indexes every contributor doc (development, architecture, > translation, contributing, localized READMEs). @@ -99,7 +102,3 @@ Execution paths: page scripts → `chrome.userScripts`; background → SW → Of > Two conventions are enforced via built-in rules in `eslint.config.mjs`: `no-restricted-imports` bans `@radix-ui/react-*` single packages (use the merged `radix-ui`) and the `sonner` `toast` export (use `notify`); `no-restricted-syntax` bans `forwardRef` across `src/pages/**` (use React 19 `function` + ref-prop). All four syntax-based harness rules are covered by `eslint-rules/harness.test.mjs`. > > Separately, type-aware rules run on `src/pages/**` (tests excluded) via `projectService` — `@typescript-eslint/no-floating-promises`, `no-misused-promises` (with `checksVoidReturn.attributes: false`, so `async` JSX handlers are allowed), and `await-thenable`, all `error` — to catch missing `await`s and promises misused as void callbacks. These need type information, so they are *not* part of `harness.test.mjs`. - -## Pull Request Description Format - -Detailed PR description guidance lives in [`docs/pull-request.md`](docs/pull-request.md). Start from the human-facing template, preserve its checklist, and expand the description only when the change needs more context. Do not claim human review or other evidence that did not happen. diff --git a/docs/DOC-MAINTENANCE.md b/docs/DOC-MAINTENANCE.md index 64679645e..990b64a11 100644 --- a/docs/DOC-MAINTENANCE.md +++ b/docs/DOC-MAINTENANCE.md @@ -100,7 +100,7 @@ git ls-files eslint-rules/; git grep -l "require-last-error-check" -- eslint.con Link integrity — confirm every relative markdown link in the core docs resolves: ```bash -for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do +for doc in AGENTS.md docs/README.md docs/DOC-MAINTENANCE.md docs/develop.md docs/references/develop-testing.md docs/pull-request.md docs/design.md docs/references/design-tokens.md docs/references/design-components.md docs/references/design-patterns.md docs/architecture.md docs/references/architecture-services.md docs/references/architecture-data.md docs/references/architecture-gm-api.md docs/references/architecture-execution.md docs/references/architecture-build.md docs/verification.md docs/references/verification-debugging.md docs/references/verification-report-template.md docs/cloud-sync.md docs/translation.md; do # the sed pipeline drops fenced code blocks and inline code spans first, so illustrative sample # links inside ```md snippets or `single-backtick` text (e.g. references/verification-report-template.md's # screenshot/resource examples, verification.md's "Evidence location" spans) aren't false-flagged as broken diff --git a/docs/pull-request.md b/docs/pull-request.md index b3e4ce25c..bac8c4953 100644 --- a/docs/pull-request.md +++ b/docs/pull-request.md @@ -1,6 +1,10 @@ # Pull Request Description Guide -This guide defines the detailed PR description format for agents and contributors. The human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) intentionally remains lightweight; use it as the starting point and expand its `Description / 描述` section when the change needs more context. +This guide defines the detailed PR description format for agents and contributors. Start from the human-facing template at [`../.github/pull_request_template.md`](../.github/pull_request_template.md) — it intentionally remains lightweight. Preserve its `Checklist / 检查清单` section, and expand its `Description / 描述` section only when the change needs more context. + +Whatever headings you use, this guide's checklist and evidence expectations still apply — `## Summary` / +`## Test plan` headings don't exempt a PR from them. Use the structure below; its sections are +recommended, not all mandatory (see below for which ones). ## Recommended structure @@ -48,7 +52,7 @@ For a normal feature or behavior change, use the following sections when they ar `Checklist`、`背景`、`本次改动` and `验证` are the recommended core for a normal feature or behavior change, not mandatory headings for every PR. Add `实现考虑` for meaningful design or concurrency implications; add `已知限制` and `建议审查重点` when reviewers need explicit boundaries or risk areas. `参考` and `关联` are optional. -Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR. +Small documentation, dependency, or CI changes may use a shorter description and omit sections that do not apply, but must still explain what changed and what was checked. For visual changes, retain the template's screenshot section and provide the relevant evidence. Never claim a test, review, screenshot, or recording that did not happen. Leave `Code reviewed by human` unchecked unless a human has actually reviewed the PR — the same applies to any other checklist item: leave it unchecked (without rewording it) whether the work wasn't done or doesn't apply. If an item doesn't apply to this PR, add a brief `N/A — ` note below the checklist, so reviewers can tell "not applicable" from "not done" — an unchecked box alone doesn't distinguish the two. ## Review-oriented content