Back to Details

make-pr-easy-to-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Make PR Easy to Review

让PR易于评审

Prepare a PR so a reviewer can quickly understand the intent, important files, and risk. The default goal is reviewability without behavior changes.
为PR做好准备，使评审人员能够快速理解其意图、重要文件和风险。默认目标是提升可评审性，同时不改变代码行为。

Workflow

工作流程

  1. Resolve the target PR from the user-provided URL or current branch.
  2. Inspect commits, diff size, changed paths, generated files, and PR description.
  3. Identify reviewability issues: noisy commits, stale description, unrelated changes, mixed mechanical and logic changes, missing tests, or unclear reviewer entry points.
  4. Propose a plan before rewriting history or force-pushing.
  5. Apply safe improvements, then verify the tree or diff still matches the intended code.
  1. 从用户提供的URL或当前分支解析目标PR。
  2. 检查提交记录、差异大小、变更路径、生成文件以及PR描述。
  3. 识别可评审性问题：杂乱的提交记录、过时的描述、无关变更、机械性修改与逻辑修改混合、缺少测试或评审入口不明确。
  4. 在重写历史或强制推送前，先提出改进方案。
  5. 应用安全的改进措施，然后验证代码树或差异是否仍与预期代码一致。

History Cleanup

历史记录清理

Only rewrite history when the user asks for it or agrees to the plan. Before rewriting:
bash
gh pr view <PR> --json title,headRefName,baseRefName,state,commits
git fetch origin <headRefName> <baseRefName>
ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})
Good commit groupings usually follow dependency order:
  1. Schema/storage or generated API definitions.
  2. Core logic.
  3. Wiring and integration.
  4. UI or surface behavior.
  5. Tests.
After rewriting, verify content identity:
bash
echo "Original tree: $ORIGINAL_TREE"
echo "Current tree:  $(git rev-parse HEAD^{tree})"
git diff origin/<headRefName> --stat
Do not push if the tree changed unintentionally.
仅当用户要求或同意改进方案时，才重写历史记录。重写前执行以下操作：
bash
gh pr view <PR> --json title,headRefName,baseRefName,state,commits
git fetch origin <headRefName> <baseRefName>
ORIGINAL_TREE=$(git rev-parse origin/<headRefName>^{tree})
良好的提交分组通常遵循依赖顺序：
  1. 架构/存储或生成的API定义。
  2. 核心逻辑。
  3. 连接与集成。
  4. UI或表面行为。
  5. 测试。
重写后，验证内容一致性：
bash
echo "Original tree: $ORIGINAL_TREE"
echo "Current tree:  $(git rev-parse HEAD^{tree})"
git diff origin/<headRefName> --stat
若代码树意外变更，请勿推送。

Reviewer Guidance

评审指导

When code behavior should stay untouched, prefer PR description and review notes:
  • Add a TL;DR that matches the actual diff.
  • Separate core files from generated or mechanical files.
  • Call out risky behavior changes, migration order, rollout plan, and test coverage.
  • Link issue trackers, dashboards, or design docs when they explain intent.
当代码行为需保持不变时，优先优化PR描述和评审说明：
  • 添加与实际差异匹配的TL;DR（摘要）。
  • 将核心文件与生成文件或机械性修改文件分开。
  • 突出高风险行为变更、迁移顺序、发布计划和测试覆盖范围。
  • 链接问题追踪器、仪表盘或设计文档以解释意图。

Guardrails

防护规则

  • Never hide meaningful behavior changes inside "cleanup".
  • Do not bypass hooks unless the user explicitly asks.
  • If the PR is too large to make reviewable with notes, recommend splitting instead of polishing around the problem.
  • 切勿在“清理”操作中隐藏有意义的行为变更。
  • 除非用户明确要求，否则不要绕过钩子。
  • 若PR过大，无法通过添加说明提升可评审性，建议拆分PR而非勉强优化。