Background

Community Configuration introduces a concept of schema version migrations, which was introduced to allow developers improve their schemas, even if it means changing the format of the configuration. The basic version of schema version migrations was introduced in T358799. Migrations consist of several attributes:

• the client extensions maintains a history of its schema versions,
• for each version, two migrations can be provided, which will reformat the configuration data conforming to one schema version to a newer one,
• a maintenance script exists that allows sysadmins to migrate the stored configuration to a defined schema version

Problem

Migrations are currently far from intuitive: unless you have a great understanding of how they are implemented, it is difficult to predict what the consequence of your actions will be. This discourages developers (and sysadmins) from making use of the migrations, decreasing the overall usability of the feature. If a migration is executed incorrectly, it has a potential of causing a lot of mess at a lot of wikis, where the mess might be hard to clean up.

In addition to the lack of intuitivity, migrations are also not conforming to a releases-based upgrade cycle. At the Foundation, we upgrade our wikis very often (running close to the master branch), which means we need to do necessary upgrades manually using individual scripts. However, the majority of external wikis upgrades from release to release, making use of the update.php script. Migrations in Community Configuration do not hook there, making it harder to use MediaWiki-extensions-CommunityConfiguration externally.

Brought by a contributor:

According to § Run the migration, the wiki administrator needs to run a separate maintenance script to keep the extension working. On WMF wikis, it’s no problem, since you want to migrate on your own cadence anyway, but on third-party wikis, it’s just another thing the administrator needs to remember doing. Couldn’t it be integrated into update.php so that it’s automatically run as part of the standard upgrade process? —@Tacsipacsi

Note: the maintenance script update.php mentioned in the comment helps migrating database schemas across MW versions. However the nature of CC schemas is different, and its versioning is not dependent on MW versions.

Task scope

Within this task, the Growth team should review the usability of migrations (paying attention to the problems mentioned in the problem description above). Improvements that contribute to the usability of the migrations should be tracked as subtasks.