Community configuration 2.0 makes it possible for developers to specify configuration schemas, which include certain configuration variables and the expected format for each. Occasionally, the expected format needs to change. In the Community configuration 1.0 implementation, this requires a developer to manually ensure each configuration file continues to be valid. However, this is not really sustainable.
Within this task, we should create a system that would make it possible for developers to easily migrate between schema versions. This script would (somehow) find PHP callables that can migrate the configuration values from one format to another. Completing T351232: Community configuration 2.0: Consider generating JSONSchema from PHP classes rather than committing them directly before (where callables are easier to register than in raw JSON) might be helpful.
Implementation Plan
- T362042: Community configuration: Introduce validation warnings
- Version the schemas internally, so that it is possible to access older version of the schema within PHP
- This can be a Migrations subfolder to the Schemas folder, with files such as MentorshipSchema_1_0_0.php, which would have the migration. The goal here is to be able to validate config files against a specific version while running the migration (so that invalid migration commands are detected, rather than saved through).
- There would need to be a script to be executed every time someone modifies a schema, which would update the Migrations subfolder. There also would likely need to be a CI structure test that'd ensure the command is being executed.
- This includes storing the schema version within the configuration store.
- Only allow changes that do not break backwards or forwards compatibility (as to schema validity; it would be the client extension's responsibility to not break on train deployments/rollbacks as to how the config is being used), so that config files don't fully break even when train moves forward or rollbacks. With the validation warnings mentioned above, this would restrict ourselves to: adding a new config variable, removing a config variable and similar changes.
- Store migration callbacks within the schema PHP class, which would accept a stdClass (with the config data conforming to a specific schema version), migrate it to a newer (older) version of the schema and return it back.
- Create a maintenance script which would convert a given provider to a specified schema version (or the newest schema, if instructed).
Acceptance Criteria
- Maintenance script to trigger the migration system
- Technical documentation
- Exploration for how we should document previous schemas