設定ファイルのマイグレーション

アプリの更新で設定キーを改名・移動したり，値の形式を変えたりする場合に使います。移行内容はスキーマへ記述し，Settingsが起動時に設定ファイルへ適用します。ユーザーの値を手作業で移し替える必要を減らせます。

バージョンと移行内容

schema_version = 2
migration_version_key = "schema_version"

[[migration]]
version = 2

[[migration.rename]]
from = "display.font_size"
to = "general.font_size"

[[migration.delete]]
key = "display.tick_rate"

[[migration.transform]]
from = "mode"
to = "vivarium.enabled"
type = "enum_to_bool"
match = "vivarium"

これはスキーマの一部です。通常の[[tabs]]などと同じスキーマに追加します。

項目	意味
schema_version	到達させたい設定バージョン。省略すると移行は実行しない
migration_version_key	設定ファイルに到達済みバージョンを記録するキー。省略時はschema_version
[[migration]]のversion	この移行が適用するバージョン。同じ番号を重複させず，目標以下にする
[[migration.rename]]	fromの値をtoへ移動。同じテーブル内の改名にも使用
[[migration.delete]]	keyを削除
[[migration.transform]]	移動と変換。type = "rename"または"enum_to_bool"
match	enum_to_boolで必須。元の値がこの文字列ならtrue，それ以外はfalse

起動時の動作

記録済みバージョンがなければ0として扱い，記録済みより大きく，目標以下の移行を番号順に実行します。完了すると目標バージョンを設定ファイルへ記録して保存します。すでに目標以上なら処理しません。

元のキーがなければその移動・変換は何もしません。移動先がすでにある場合も，その既存値を優先して移動をスキップします。処理によって空になった親テーブルは取り除かれます。適用順は移行ごとにrename，transform，deleteです。

移行は設定画面を表示する前に実行・保存されます。Windows・Linuxの通常の編集でCancelを押しても，起動時に済んだ移行を取り消す動作にはなりません。

検証と試し方

settings-schema-checkerで，バージョンの重複や目標超過，enum_to_boolのmatch不足などを確認できます。

実際の移行は，旧形式のconfig.tomlのコピーを用意して確認します。Settingsをそのコピーのパスで起動し，移行後のキー・値・記録バージョンを確認してください。移行定義はスキーマに埋め込まれるため，変更した場合はビルドし直します。