[studio] .yaml migration

[oliviertassinari]

Summary

When upgrading Toolpad, we usually update the YAML files.

-# yaml-language-server: $schema=https://raw.githubusercontent.com/mui/mui-toolpad/v0.1.53/docs/schemas/v1/definitions.json#properties/Page
+# yaml-language-server: $schema=https://raw.githubusercontent.com/mui/mui-toolpad/v0.1.55/docs/schemas/v1/definitions.json#properties/Page

which can be missed from the upgrade, e.g. with renovate: https://github.com/mui/mui-private/pull/473 + https://github.com/mui/mui-private/commit/a1a8c070347e14f9a0c999efd26a4e94aaea9c17

Should we:

1. Automatically check that the version is correct when starting Toolpad?
   Or have a script that check that the versions are correct, e.g. pnpm i https://pnpm.io/cli/install

2. Do it like pnpm, only update the version if there was a migration, e.g. https://github.com/mui/mui-private/pull/473/files#diff-1033a05e142dd98448ec5e563e5cbf1a86563007ee9f36efb54481e0ec29e036R1?

-lockfileVersion: '6.0'
+lockfileVersion: '9.0'

Examples

No response

Motivation

No response

Search keywords: -

[Janpot]

These comments are only meant to instruct a vscode extension to do autocomplete. They're not meant as a versioning.

The current versioning philosophy was to be backwards compatible as long as the apiVersion property in the yaml matches. e.g. Toolpad should be able to run a project that was created in a lower version. However, this is probably not maintainable in the long run as there is no way of determining whether the file created comes from a newer or older Toolpad version.

We should likely do 1. as even when the schema doesn't change, Toolpad may behave differently across versions. a schema created with one version may not necessarily work as intended with a higher Toolpad version

I propose we move to the following versioning behavior:

1. Add the exact version of Toolpad that created/wrote the file in the yaml
2. On startup of app
   • if yaml version > toolpad version => show error and exit
   • if yaml version < toolpad version => if it's being run with the --migrate flag, migrate and run the app, otherwise show error and exit
3. On startup of editor
   • if yaml version > toolpad version => show error and exit
   • if yaml version < toolpad version => propose to migrate the project to latest version or instruct user to install lower version of Toolpad. Migrate the app if the user confirms. Do not run the editor until the versions match