Discourse テーマ設定の移行

ドキュメント 開発者ガイド
1

はじめに

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 で提案してください。

「いいね！」 8