Discourseテーマ設定を移行

序論

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 でお願いします。

「いいね!」 9