This guide owns the PR body: structure, evidence, and reviewer-handoff expectations. It does not own
commit message or PR title rules — those live in
develop.md § Commit & Pull Request Guidelines (gitmoji prefix,
single-purpose commits). Start from the human-facing template at
../.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).
For a normal feature or behavior change, use the following sections when they are meaningful:
## Checklist / 检查清单
- [ ] Fixes ... / 已修复或实现 ...
- [ ] Code reviewed by human / 代码通过人工检查
- [ ] Changes tested / 已完成测试
## 背景
<!-- What problem, compatibility gap, or maintenance need does this solve? -->
## 本次改动
<!-- Summarize user-visible behavior and important implementation changes. -->
## 实现考虑
<!-- For non-trivial changes: explain key design decisions, invariants, races, or compatibility choices. -->
## 已知限制
<!-- Record explicit scope boundaries, unsupported cases, and follow-up work. -->
## 建议审查重点
<!-- List concrete behaviors or risks reviewers should verify. -->
## 参考
<!-- Specs, documentation, code locations, or external API references. -->
## 关联
<!-- Related issues or PRs, using links or closing keywords when applicable. -->
## 验证
<!-- Exact commands and concise results. Include known warnings or explain why a check was not run. -->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 — 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 — <why> note below the checklist, so reviewers can tell "not applicable" from "not done" — an unchecked box alone doesn't distinguish the two.
The brief N/A note above is only for an inapplicable PR checklist item. Test dimensions remain applicability-gated by the testing guide and are omitted when they do not apply; do not add a formal applicability table or proof packet to a PR.
For a material behavior, configuration, security, performance, compatibility, persistence, migration, release, or refactor change, write enough context for a reviewer to reconstruct:
- the problem or requirement;
- the affected scope and consequence;
- the evidence that the premise is real;
- why action is justified;
- the selected remedy and material trade-off;
- acceptance evidence; and
- the remaining limitation or risk.
Keep this chain proportional. A confirmed one-line correction or a small documentation fix needs only the material parts; a non-trivial design choice should explain why doing nothing or a plausible smaller alternative was not selected and what would reopen the decision.
Keep these roles separate:
- maintainer direction authorizes execution within the requested scope;
- an issue, PR description, or discussion supplies stated intent and scope context;
- source inspection, tests, browser runs, and integrations provide observations;
- a specification, compatibility contract, security policy, accepted test oracle, or maintainer decision owns normative correctness.
An issue or PR does not by itself prove that a bug exists, that a remedy is necessary, that a change is correct, or that external publication or residual-risk acceptance is authorized.
Consider risk for every material change. Use an explicit limitation or rollback paragraph when the change affects shared APIs, persistence, permissions, security/privacy, browser compatibility, cross-context messaging, asynchronous lifecycle, or release/build behavior. Identify residual risk and the decision owner; do not claim that a significant residual risk has been accepted without that owner's decision.
An agent must not present a change as review-ready when a material acceptance condition fails, a critical claim is unverified or contradicted, the diff exceeds the justified scope, required verification is missing without an adequate substitute, a known correctness/security/privacy/compatibility defect remains, or the description no longer matches the final patch. An explicitly requested draft or investigation may still be submitted when labeled as such. Report the blocker, the evidence, and the condition that would clear it.
Verification claims bind to a revision or clearly identified worktree. If code, configuration, generated artifacts, or a decision-relevant description changes after a check, rerun every affected check before claiming readiness. A final commit SHA is sufficient identity for ordinary GitHub work; a cryptographic evidence ledger is not required by default.
Activate only the rows touched by the actual change; mixed changes use their union.
| Changed contract | Extra evidence to expect |
|---|---|
| Bug fix | Before reproducer, expected behavior, regression test or justified manual evidence, and the same reproducer after the fix |
| New behavior | User/system need, observable acceptance criteria, and compatibility/scope boundaries |
| Refactor | Concrete structural problem and evidence that behavior/public contracts are preserved |
| Performance/resource | Baseline, workload, environment, method, before/after result, and accepted correctness/complexity trade-off |
| Security/privacy/permissions | Protected boundary, threat or failure mode, safe verification, residual risk, and private reporting when appropriate |
| Dependency/build/configuration | Compatibility or lifecycle reason, version/platform scope, lock/generated rationale, and build verification |
| Documentation/tests only | The authoritative behavior or decision being corrected or preserved; verify claims, links, or tests without inventing runtime evidence |
| Generated/mechanical | Source input, tool/command, reason for regeneration, and evidence that unrelated semantic edits were not mixed in |
| Persistence/migration/release | Compatibility and data scope, ordering/irreversibility, rollback/restore path, and rehearsal or invariant evidence where safe |
| Async/concurrency/stateful UI | Duplicate in-flight work, stale or late results, cancellation/retry, cleanup, and identity or generation ordering where applicable |
For non-trivial changes, make the description useful for review:
背景explains the problem, compatibility gap, or maintenance need.本次改动summarizes user-visible behavior and important implementation changes.实现考虑records design decisions, invariants, lifecycle behavior, races, or compatibility choices.已知限制records unsupported cases, explicit scope boundaries, and follow-up work.建议审查重点lists concrete behaviors or risks reviewers should verify.验证lists exact commands and concise results, including known warnings or why a check was not run.
For a PR that only changes Markdown, 验证 should reflect what a doc change actually needs, not an unrelated
full code test suite: a fact check against the final tree, a relative-link/actual-anchor check, a
cross-document policy-consistency check, and a privacy/sanitization scan (see
DOC-MAINTENANCE.md). Before writing "all fixed" or "fully verified," re-review your
own final diff and any nearby location sharing the same root cause — but only claim the scope you actually
scanned; don't imply full-repo coverage you didn't perform.