Draft a Migration Guide for a Breaking Change That Users Can Follow Without Asking Questions

0 upvotes
Write a migration guide for a breaking change. Your reader is a developer who uses our library or API, is busy, and wants to know three things quickly: does this affect me, what exactly do I change, and how do I know it worked.

<change_summary>
[Describe what changed, in the engineers' own words]
</change_summary>

<old_behavior_and_code>
[Paste the old API usage, config, or behavior]
</old_behavior_and_code>

<new_behavior_and_code>
[Paste the new API usage, config, or behavior]
</new_behavior_and_code>

<extra_context>
Why the change was made: [reason]
Version where it takes effect: [version]
Any deprecation period or compatibility flag: [details or "none"]
</extra_context>

Produce a guide with these sections:
1. "Am I affected?" Give a short, checkable test (a search pattern, a config key, or an error message they would see). Use only information I provided. Don't invent specifics.
2. "What changed and why" in at most four sentences.
3. "How to migrate" as numbered steps. Each step shows a before/after code snippet drawn from my input. If a step has more than one valid path, say how to choose.
4. "How to verify" listing the observable signs that the migration worked, and the most likely failure symptom with its cause.
5. "Rollback or escape hatch" if one exists. If I didn't mention one, write "None documented" and do not invent one.

Rules: Do not claim anything about behavior that isn't in my input. If something needed for a complete guide is missing, list it under "Questions for the author" at the end instead of filling the gap. Keep the tone plain and direct, with no marketing language.