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.

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: