WordPress plugin: update migrations

Use this for code that must change stored plugin data when the installed code version advances. This is not activation/deactivation/uninstall; use wp-plugin-lifecycle for those boundaries. Update migrations must be idempotent, stepwise, and safe to re-run after a partial failure.

Why this is separate from activation

Activation does not fire on normal plugin update. WordPress also performs update internals in ways that make activation/deactivation hooks the wrong surface:

• register_activation_hook() runs when the plugin is activated or reactivated, not when files are replaced by an update.
• Plugin_Upgrader::deactivate_plugin_before_upgrade() silently deactivates active plugins in browser updates; silent deactivation prevents deactivation hooks from firing.
• Active plugins are loaded in wp-settings.php before wp-admin/update.php creates Plugin_Upgrader. An upgrader_process_complete callback registered by the plugin is usually old code already loaded in memory. Do not assume that callback can call new migration classes.
• Inactive plugins do not load, so their upgrader_process_complete callbacks are not registered at all.

The reliable pattern is: store a schema/data version in an option, compare it to the current code's schema version on normal plugin boot, and run missing steps with the new code loaded.

When to use this skill

Trigger when ANY of the following is true: