migration guide missing renamed config key, upgrade broken
Fixes migration guides that omit a renamed config key, breaking upgrades. Use it when users upgrade and the app ignores or rejects their config. Key trigger: a config key was renamed in code but the guide still documents the old name.
TL;DR
Add the renamed key to the migration guide with the old name, the new name, and the exact config edit users must make, then republish. Upgrades break because users keep the old key and the app silently ignores it or fails to start. Find the rename commit to confirm both names and the version it shipped in, and test the documented upgrade path yourself.
The error
migration guide missing renamed config key, upgrade brokenSteps
- Find the rename commit:
git log -S "old_key" --oneline -- config/(use the actual old key name). Expected: the commit that renamed it, with the version it shipped in. - Confirm both names and the behavior with the old key (ignored silently vs hard error). Expected: you know exactly what a user with the old key experiences.
- Write the migration entry: old key name, new key name, the file to edit, and a before/after snippet. Expected: a user can apply the fix without reading the source.
- Test it: put the old key in a config, run the new version, confirm the failure; apply the documented edit, confirm it starts. Expected: the guide's steps resolve the exact break you reproduced.
- Republish the guide. Expected: the renamed key appears in the migration notes for the right version.
Use this when
- A migration guide omits a config key rename and upgrades break.
- Users report the app ignoring their config after an upgrade.
- A rename shipped in code but the guide was never updated.
Not for this skill when
- The guide documents the rename and users still fail - that is a different bug in the migration logic.
- The key was removed outright with no replacement - document the removal, not a rename.
- You are deciding the new key name - that is a design call, not a docs fix.
Variant phrasings
upgrade broken by renamed config option
Same, reported from the upgrade failure. Same fix.
migration guide missing config change
Same for non-rename config changes the guide skipped. Same fix.
old config key ignored after upgrade
Same symptom seen from the user's config file. Same fix.
Why it happens
Renames are one-line code changes that feel too small to document, so they ship without a guide update. The old key then fails in the worst way: silently ignored, so the app runs with default behavior instead of the user's intent, and the user blames the upgrade rather than the missing note.
Edge cases
- Silent ignores are worse than errors: if the app errors on unknown keys, users find the problem fast. Prefer fail-fast validation for renamed keys, and document the error message in the guide.
- Multiple renames across versions: users skipping versions need every intermediate rename, not just the latest. List the full chain or the direct old-to-new mapping per starting version.
- Env var equivalents: if the key also exists as an environment variable, document both renames.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_BwhGZfWuAPfnc93LjADncQ
Maintainer review
No maintainer verification is recorded for this version.
This records the version a maintainer checked. It does not assert that the version is the latest upstream release.