序論
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桁にする必要があります。同じ理由から、現在、1つのテーマに9999件を超えるマイグレーションを持つことはできませんが、将来変更される可能性があります。
マイグレーション関数
クラス、関数、配列、マップなど、標準的な JavaScript の 機能 は、マイグレーションで使用できます。Discourse コアの唯一の期待値は、各マイグレーションファイルがエントリーポイントとして機能するデフォルト関数をエクスポートする必要があるということです。この関数は、変更されたテーマ設定を表す Map オブジェクトを受け取り、すべての設定の最終的な望ましい状態を反映する Map オブジェクトを返します。
例
テーマ設定の名前を変更する:
// ファイル名: 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 ファイルでの設定の名前変更と伴に行う必要があります。
カンマ区切り文字列設定を正しいリストに変換する:
// ファイル名: 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 設定の選択肢の名前を変更する:
// ファイル名: 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;
}
リスト設定に新しい項目を追加する:
// ファイル名: 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;
}
テキスト設定をテーマ翻訳へ移動する
文字列設定をテーマ翻訳に置き換える場合は、helpers.migrateSettingToTranslation(settingName, translationKey) を使用します:
// ファイル名: 0002-migrate-heading.js
export default function migrate(settings, helpers) {
helpers.migrateSettingToTranslation("heading_text", "homepage.heading");
return settings;
}
同じ更新で settings.yml から heading_text を削除し、locales/en.yml で保存先を宣言します:
en:
homepage:
heading: ""
ヘルパーは、保存された設定を英語のテーマ翻訳オーバーライドへ移動し、設定を削除します。英語は他の言語のフォールバックロケールであるため、そのロケール用の翻訳が提供されるまで、訪問者は保存されたテキストを表示し続けます。同じキーを宣言するロケールファイル(値が空の場合であっても)は、そのロケールで保存された英語テキストを隠します。これは将来の更新で追加されたロケールファイルにも適用されます。
- ヘルパーは、マイグレーションに渡される
settingsマップから読み取ります。保存された設定のみがマイグレーションされます。旧設定に空でないデフォルト値があった場合は、保存された値がないサイトがテキストを保持するように、en.ymlでそのデフォルト値を使用してください。 - 設定の値は文字列である必要があり、保存先は宣言済みのテキストキーである必要があります。空の文字列は保持されます。
- 既存の英語オーバーライド(空のものを含む)は上書きされません。複数のマイグレーションが同じキーをターゲットにする場合、最初にマイグレーションされた値が優先されます。
- 実行時環境は、データベースに書き込まずに翻訳変更を準備します。Discourse は設定およびマイグレーションレコードと同じトランザクションでそれらを保存し、更新が失敗した場合はすべてロールバックします。
- マイグレーションログは削除された設定の値を保持します。テーマコードを元に戻しても、翻訳オーバーライドが設定に戻されることはありません。
実行とエラー処理
マイグレーションは、テーマのインストールおよび更新中に自動的に実行されます。一度だけ実行されます。マイグレーションが正常に実行された後に変更されても、再度実行されることはありません。マイグレーションが失敗した場合、更新プロセスは停止し、何が間違っていたかのエラーメッセージが表示されます。
マイグレーションにバグがあり、設定の破綻した状態が発生した場合は、元のマイグレーションを変更するのではなく、破綻した状態を修正する新しいマイグレーションを作成することが、問題解決の正しい方法です。
このドキュメントはバージョン管理されています - 変更の提案は GitHub でお願いします。