はじめに
Discourse バージョン 3.2.0.beta3 以降、Discourse のテーマ/コンポーネントはマイグレーション機能を利用して、設定をシームレスに変更・進化させることができます。この機能により、テーマの更新時に設定の変更が制御された方法で処理されるため、既存のインストールが中断されることがなくなります。
マイグレーションを使用するタイミング
マイグレーションが特に役立つ一般的なシナリオは次のとおりです。
- 設定のタイプを変更する場合（例：コンマ区切り文字列からリストへ）。
- 設定の名前を変更する場合。
- 設定に保存されているデータの構造や形式を変更する場合。
これらのシナリオでは、マイグレーションを伴わずに settings.yml ファイルで設定のタイプや名前が変更された場合、設定をデフォルト値から変更していた既存のインストールでは、その設定に対する変更が失われ、テーマが更新されると破損する可能性があります。
テーマ設定を更新する際の円滑な移行を保証するために、テーマ開発者は、古いバージョンの settings.yml に準拠した既存の状態を新しいバージョンに移行する方法を Discourse コアに指示するマイグレーションを同梱する必要があります。
マイグレーションファイル
マイグレーションは、テーマの migrations/settings ディレクトリにある JavaScript ファイルで、命名規則 XXXX-migration-name.js に従います。XXXX プレフィックスはバージョン番号であり、0001 から順次増えていき、実行順序を決定します。
名前は、マイグレーションの目的を簡潔に説明するもので、英数字とハイフンに限定され、150 文字未満である必要があります。マイグレーションは、バージョンの数値に基づいて昇順で実行されます。
最初のマイグレーションには 0001、2番目のマイグレーションには 0002 のように開始することを推奨します。マイグレーションのバージョンが 1000 未満の場合、マイグレーションファイル名は 4 桁の数字で始まる必要があるため、バージョンを先頭にゼロを埋めて 4 桁にする必要があります。同じ理由で、現在、テーマで 9999 を超えるマイグレーションを持つことはできませんが、これは将来変更される可能性があります。
マイグレーション関数
標準の JavaScript の機能（クラス、関数、配列、マップなど）はすべてマイグレーションで使用できます。Discourse コアからの唯一の要件は、各マイグレーションファイルがエントリポイントとして機能するデフォルト関数をエクスポートすることです。この関数には、変更されたテーマ設定を表す Map オブジェクトが渡され、すべての設定の目的の最終状態を反映する Map オブジェクトを返します。
例
テーマ設定の名前を変更する:
// filename: 0001-rename-old-setting.js
export default function migrate(settings) {
if (settings.has("old_setting_name")) {
settings.set("new_setting_name", settings.get("old_setting_name"));
settings.delete("old_setting_name");
}
return settings;
}
このマイグレーションは、settings.yml ファイルでの設定名の変更と同時に行われる必要があります。
コンマ区切り文字列の設定を適切なリストに変換する:
// filename: 0001-convert-string-setting-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split(",");
settings.set("list_setting", list.join("|"));
}
return settings;
}
前の例と同様に、このマイグレーションは、settings.yml ファイルで設定タイプを string から list に変更することと同時に行われる必要があります。
enum 設定の選択肢の名前を変更する:
// filename: 0001-rename-enum-choice.js
export default function migrate(settings) {
if (settings.get("enum_setting") === "old_option") {
settings.set("enum_setting", "new_option");
}
return settings;
}
リスト設定に新しい項目を追加する:
// filename: 0001-add-item-to-list.js
export default function migrate(settings) {
if (settings.has("list_setting")) {
const list = settings.get("list_setting").split("|");
list.push("new_item");
settings.set("list_setting", list.join("|"));
} else {
settings.set("list_setting", "new_item");
}
return settings;
}
実行とエラー処理
マイグレーションは、テーマのインストールおよび更新中に自動的に実行されます。これらは一度だけ実行されます。正常に実行された後にマイグレーションが変更されても、再度実行されることはありません。マイグレーションが失敗した場合、更新プロセスは停止し、何が問題であったかを示すエラーメッセージが表示されます。
マイグレーションにバグがあり、設定の破損した状態につながった場合、問題を修正する正しい方法は、元のマイグレーションを変更するのではなく、破損した状態を修正する新しいマイグレーションを作成することです。
このドキュメントはバージョン管理されています - 変更の提案は github で行えます。