Engineering Change Descriptions

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?

First Line

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

Body

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

Templates

Standard PR

[Imperative one-line summary]

## Why
[Problem, user need, production issue, maintainability reason, or design context.]

## What Changed
- ...
- ...

## Testing
- ...

## Risk / Rollback
- Risk:
- Rollback:

Small Change

[Imperative one-line summary]

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

Testing: [command or manual check]

Refactor

[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]

Generated or Mechanical Change

[Describe the mechanical rewrite]

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

Verification: [format/test/build command]

Rewrite Checklist

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.

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.