Back to Details

engineering-change-descriptions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Engineering Change Descriptions

工程变更描述

A change description is permanent engineering history. It should let reviewers understand the change now and help future maintainers find and understand it later.
Adapted from Google Engineering Practices Documentation, especially "Writing good CL descriptions." Source: https://google.github.io/eng-practices/review/developer/cl-descriptions.html. License: CC-BY 3.0.
变更描述是永久性的工程历史记录。它应能让审核者当下理解变更内容，并帮助未来的维护者找到并理解该变更。
本文改编自谷歌工程实践文档，尤其是《撰写优质CL描述》一文。来源：https://google.github.io/eng-practices/review/developer/cl-descriptions.html。许可证：CC-BY 3.0。

What a Good Description Answers

优质描述应解答的问题

  • What changed?
  • Why did it change?
  • What context, constraints, or tradeoffs are not obvious from the code?
  • How was it tested?
  • What risks, migrations, rollbacks, or follow-ups should reviewers know?
Even small changes deserve context when the reason is not obvious.
  • 变更了什么？
  • 为什么要变更？
  • 代码中未体现的背景、约束或权衡是什么？
  • 如何进行测试的？
  • 审核者需要了解哪些风险、迁移、回滚或后续工作？
即使是小变更，当变更原因不明显时也需要提供背景信息。

First Line

首行要求

The first line should:
  • Stand alone in version control history.
  • Be short, specific, and focused on what the change does.
  • Use an imperative form when writing a commit or CL title.
  • Avoid vague labels like "fix bug", "cleanup", "phase 1", "misc", or "add helpers".
  • Be followed by a blank line when there is a body.
首行应满足：
  • 在版本控制历史中可独立理解。
  • 简洁、具体，聚焦于变更内容。
  • 撰写提交信息或CL标题时使用祈使语气。
  • 避免使用模糊标签，如“修复bug”、“清理”、“第一阶段”、“杂项”或“添加辅助工具”。
  • 当存在正文时，首行后需空一行。

Body

正文要求

Include only useful context:
  • Problem being solved.
  • Why this approach was chosen.
  • User-visible or developer-visible behavior changes.
  • Important implementation notes.
  • Known limitations or follow-up work.
  • Bug IDs, issue links, benchmark results, design docs, migration docs, or rollout plans.
  • Enough context for links that might later become inaccessible.
  • Test commands and results, when appropriate.
Before submitting, reread the description after review changes and make sure it still matches the final diff.
仅包含有用的背景信息：
  • 要解决的问题。
  • 选择此方案的原因。
  • 用户可见或开发者可见的行为变更。
  • 重要的实现说明。
  • 已知限制或后续工作。
  • Bug编号、问题链接、基准测试结果、设计文档、迁移文档或发布计划。
  • 为可能日后无法访问的链接提供足够背景。
  • 适当时提供测试命令和结果。
提交前，需在审核变更后重新阅读描述，确保其仍与最终差异匹配。

Templates

模板

Standard PR

标准PR

markdown
[Imperative one-line summary]
markdown
[祈使语气的单行摘要]

Why

原因

[Problem, user need, production issue, maintainability reason, or design context.]
[问题、用户需求、生产问题、可维护性原因或设计背景。]

What Changed

变更内容

  • ...
  • ...
  • ...
  • ...

Testing

测试

  • ...
  • ...

Risk / Rollback

风险 / 回滚

  • Risk:
  • Rollback:
undefined
  • 风险：
  • 回滚：
undefined

Small Change

小型变更

markdown
[Imperative one-line summary]

[One paragraph explaining why this change exists and any non-obvious context.]

Testing: [command or manual check]
markdown
[祈使语气的单行摘要]

[一段解释变更原因及非明显背景的文字。]

测试：[命令或手动检查方式]

Refactor

重构

markdown
[Describe the structural change and what it replaces]

This prepares for [future change] by [specific reason], without intentionally changing behavior.

Testing: [existing or new tests that protect behavior]
markdown
[描述结构变更及替代内容]

本次重构为[未来变更]做准备，原因是[具体理由]，未刻意改变行为。

测试：[保护现有行为的已有或新增测试]

Generated or Mechanical Change

生成式或机械变更

markdown
[Describe the mechanical rewrite]

Generated by [tool/version/command] to [reason]. Manual edits: [none/list].

Verification: [format/test/build command]
markdown
[描述机械重写内容]

由[工具/版本/命令]生成，目的是[原因]。手动修改：[无/列表]。

验证：[格式/测试/构建命令]

Rewrite Checklist

重写检查清单

When improving an existing description:
  1. Extract the actual behavior from the diff.
  2. Replace vague first lines with a concrete action.
  3. Add the missing why.
  4. Preserve useful issue links and test evidence.
  5. Remove process noise that does not help reviewers or future maintainers.
优化现有描述时：
  1. 从差异中提取实际行为。
  2. 用具体动作替换模糊的首行。
  3. 补充缺失的变更原因。
  4. 保留有用的问题链接和测试证据。
  5. 删除对审核者或未来维护者无用的流程噪音。

Common Mistakes

常见错误

  • Describing only the implementation without the reason.
  • Writing a title that future searchers cannot distinguish from similar changes.
  • Depending entirely on external links for crucial context.
  • Leaving the description stale after review significantly changes the diff.
  • Hiding risk, limitations, or rollout requirements because they feel inconvenient.
  • 仅描述实现细节而未说明变更原因。
  • 撰写的标题无法让未来搜索者区分类似变更。
  • 完全依赖外部链接获取关键背景信息。
  • 审核后差异发生重大变化，但描述未更新。
  • 因觉得麻烦而隐瞒风险、限制或发布要求。