Write a migration guide for a breaking change

Shipping a major version and users have to change their code.

Write a migration guide for the breaking change below.

Structure:
1. **Who is affected**, stated so a reader can tell in ten seconds whether to keep reading. Include how to check, ideally a grep or a command.
2. **What changed and why**, two sentences. The why matters because it tells readers what else to expect.
3. **Before and after**, as code, for each affected pattern. Cover the common case first and the awkward cases after.
4. **Step-by-step migration**, in an order that leaves the codebase working after each step.
5. **Automated help**: a codemod, a regex, or a compiler flag if one exists. If none exists, say so plainly.
6. **What to do if you cannot migrate yet**: how long the old path keeps working, and what the deprecation warning looks like.

Do not minimise the effort. If a case requires a rewrite rather than a rename, say that.

The change:

Releases and decisions. Changelogs, migration guides and decision records that explain what changed and why.