Describing a change so that reviewers can review it

Goal

Give reviewers the context they need to judge the change in one reading, and leave a record that explains the change to future maintainers.

Prerequisites

A change that is small enough to review; if the description needs several sections of "also", split the change.

Steps

1. Problem: what is wrong or missing, with a link to the ticket or the observation that prompted the work.
2. Approach: what the change does and why this way; mention alternatives considered and why they lost.
3. Scope: what is deliberately not included, and any follow-up work planned.
4. Testing: what was run (automated tests, manual steps, environments) and what was not; include how a reviewer can reproduce.
5. Risk and rollout: migrations, feature toggles, backwards compatibility, monitoring to watch after deployment, rollback path.
6. Review guidance: where to look first, and which decisions you are unsure about.
7. Keep the description current as the change evolves during review; the merged description should match the merged code.

Expected result

Fewer review rounds spent on clarifying intent; a history where each merged change explains itself.

Limits and test basis

Templates help only if they are filled with substance; empty headings are noise. Trivial changes deserve a one-line description. No measurement is claimed.