pull-request.md

Pull Request Description Guide

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).

Recommended structure

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.

Review-oriented content

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.

Documentation-only PRs

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.