A project is retiring the key cache_dir. A note that says “use the new setting” still makes readers guess whether they should move the files. Show exactly what to replace and what they can keep.
Show a working-size replacement
This example uses fictional configuration keys. Put both versions next to each other and identify when the change applies in your actual project.
# Before
cache_dir = "./cache"
# After
storage_dir = "./cache"
Illustrated migration. Preserve the cache path while changing the name.
Specify the test and the affected version
State when the new key is supported, and when the old key will stop working if that is known. Tell readers to try the change in a copy of their config, load it using the new version and check that the resolved location is still ./cache relative to the intended working directory.

Illustrated migration proof. Test a copy before updating a shared file.
If both keys are present, explain how your tool chooses between them based on its actual behavior. Keep the old and new examples short enough to compare line by line.



