After updating Breadcrumb NavXT, WP Lynx, or any other plugin that used adminKit, you may be greeted with the following message on the settings page:
Your settings are out of date. Migrate now.
This post explains what is happening when “Migrate now” is clicked, and provides some background and insight as to why this message exists.
What “Migrate now” Does
Occasionally, the internal plugin settings structure changes. This can be due to many reasons including: to fix bugs, clean up internal plugin structure, remove settings. When the “Migrate now” link is clicked, within adminKit, the opts_upgrade_wrapper function is called. This function runs code specific to each plugin for upgrading/migrating settings. Additionally, it updates the version setting for the plugin.
Depending on what changed between the version of the plugin that was installed and the new version, the only change may be to the version setting. Typically, values of settings will not be changed in the update process. Additionally, changes to the settings structure only occur in feature adding releases (e.g. 1.1.0 or 1.2.0) and not bugfix releases (e.g. 1.1.1 or 1.2.1). Thus, it is safe to press “Migrate now.” on bugfix updates (e.g. from 1.1.0 to 1.1.1 or 1.2.1 to 1.2.2).
The settings page will not allow the plugin’s settings to be modified until after they have been migrated. In the interim, the plugin will merge the settings saved in the database with safe default values (the same used on install). Thanks to this design, there should always be a valid setting value available for every setting.
Some Background
Since the introduction of the settings page for Breadcrumb NavXT (know as Breadcrumb Navigation XT at the time) back in 2007, the structure of the plugin has changed numerous times. With changes in the structure came changes in the settings. In the past, the settings migration was set to occur when the plugin was activated, or ‘reactivated’ on plugin update. However, this method was unreliable since WordPress did not always, and then officially stopped, triggering the requisite action when updating a plugin.
Thus, there was a case where the settings may need to be migrated, but the default action for doing this during the update of the plugin was unreliable. This leaves two choices, either silently run the settings migration the first time the plugin’s code runs, or prompt the user to allow the action to occur. Only one of these choices is good; doing things behind the user’s back is bad.
This is how the “Your settings are out of date. Migrate now.” message was born. It allows the user to authorize the migration of their settings to the latest settings schema. At the same time, it allows the user to first test their site to see, before the settings migration, if everything works as intended after the plugin update.
-John Havlik
[end of transmission, stay tuned]