EmDash を更新する

このガイドは、サイトの運用担当者向けです。EmDash 上に構築したサイトを運用していて、より新しいリリースに更新したい方が対象です。アップデーターは、プロジェクト内のすべての直接依存関係である emdash と @emdash-cms/* を対象とします。ご自身のコレクションとフィールドの変更については、デプロイ済みサイトのスキーマを進化させるで説明しています。

リリースの互換性

EmDash はセマンティックバージョニングに従います。

• パッチリリースには、後方互換性のある修正と小さな改善が含まれます。
• マイナーリリースには、後方互換性のある機能が含まれます。
• メジャーリリースでは、既存のプロジェクトに変更が必要になることがあります。そのリリースエントリには、影響を受けるプロジェクトと必要な対応が記載されています。

emdash と @emdash-cms/cloudflare は同時にリリースされ、1 つのバージョン番号を共有します。@emdash-cms/cloudflare は、完全に一致するバージョンの emdash に依存するため、2 つのパッケージは 1 回の手順で更新してください。@emdash-cms/plugin-forms などのプラグインパッケージには独自のバージョン番号があり、必要とする最小の emdash バージョンを宣言しています。

リリースページには、パッケージとバージョンごとに 1 つのエントリがあります。upgrade-emdash は、各直接パッケージの変更履歴の範囲を、正確な GitHub リリースタグから取得します。自動生成された依存関係更新のエントリは除外し、手書きのメジャー、マイナー、パッチのエントリは完全な形で保持し、複数のパッケージで繰り返されるエントリは重複を取り除きます。

テンプレートファイルは更新されない

テンプレートからサイトを作成すると、レイアウト、コンポーネント、スタイル、astro.config.mjs など、テンプレートのファイルがプロジェクトにコピーされます。アップデーターは、EmDash の直接依存関係を変更し、EmDash のエージェントスキルを更新します。サイトのアプリケーションファイルと設定ファイルには手を加えず、プロジェクトの担当者またはエージェントが、アップグレードの作業指示書に従って変更します。テンプレートへの後からの変更は、新しいサイトにのみ適用されます。既存のサイトに取り入れるには、ご自身のファイルを templates ディレクトリにある現在のバージョンと比較し、必要な変更をコピーしてください。

更新の前に

アップデーターは、サイトのデータベースに接続せずに、プロジェクトのファイルとインストール済みパッケージを変更します。そのため、実行前にアップグレード専用のバックアップは必要ありません。インストール後、追加されたコアマイグレーションがある場合は .emdash/UPGRADE.md に記載されます。

アップグレードしたアプリケーションを起動またはデプロイする前に、次のいずれかに当てはまる場合は復旧ポイントを作成してください。作業指示書に追加されたマイグレーションが記載されている、emdash migrate --status がそれ以前の保留中のマイグレーションを報告する、またはリリースエントリがデータを変更するプロジェクトの対応を求めている場合です。設定されているデータベースについては、バックアップと復旧に従ってください。EmDash の JSON バックアップでは、サイトを復元できません。

アップデーターには emdash 0.35.0 以降が必要です。0.35.0 は、コアマイグレーションを報告する最初のリリースです。それより古いサイトでは、復旧ポイントを作成し、プロジェクトのパッケージマネージャーで emdash とその他の直接依存の @emdash-cms/* パッケージを 0.35.0 に更新し、そのリリースまでの各パッケージの変更履歴を確認してください。その後、残りの更新にアップデーターを実行します。

アップデーターは node_modules からパッケージを読み取るため、Yarn Plug’n’Play のインストールには対応していません。Plug’n’Play を使う Yarn プロジェクトでは、.yarnrc.yml に nodeLinker: node-modules を設定し、yarn install を実行してからアップデーターを実行してください。

サイトをビルドするマシンの Node.js のバージョンを確認してください。Node.js でデプロイする場合は、サーバーのバージョンも確認します。対応バージョンは初めての EmDash サイトを作成するに記載されています。

更新を計画して適用する

サイトのプロジェクトディレクトリからアップデーターを実行します。アップデーターは、インストール済みのパッケージのバージョンとコアマイグレーションの識別情報を読み取り、選択した npm の dist-tag を直接依存の EmDash パッケージごとに個別に解決します。既定のタグは latest です。--to next、--to beta などの dist-tag を指定すると、リリースチャンネルを選べます。--to には正確なバージョンは指定できません。

デプロイと検証

ビルドは、他の変更と同じ方法でデプロイします。次のコマンドは Cloudflare のサイトをデプロイします。Node.js でデプロイする場合は、新しいビルドでサーバープロセスを再起動してください。

pnpm wrangler deploy

デフォルトのランタイムマイグレーションモード auto では、デプロイされたサイトは、最初のリクエストで保留中のコアマイグレーションを適用します。必要な復旧ポイントが用意されるまで、保留中のマイグレーションを含むビルドをデプロイしないでください。新しいコードがトラフィックを受け取る前にマイグレーションを適用し、その後でデプロイ済みのデータベースを検証するには、コアデータベースマイグレーションの管理に従ってください。その emdash migrate --check コマンドは、デプロイ済みのデータベースに、インストール済みのバージョンに対する保留中または不明なマイグレーションがある場合、ゼロ以外のコードで終了します。

デプロイ後は、管理画面を開き、少なくとも 1 つの公開ページを読み込み、使い捨てのエントリを編集して公開し、使い捨てのメディアファイルをアップロードして取得します。サイトがスケジュールタスクやサンドボックス化されたプラグインを使用している場合は、それらの経路も検証してください。

特定リリース向けの注意

ほとんどのリリースでは、上記の手順以外に必要なことはありません。以下のエントリでは、EmDash がすでに保存しているデータを変更したリリースを取り上げ、あなたの対応が必要な場合はそれを示します。

変更: 参照フィールドがリレーションにバインドされる

reference フィールドは以前、ターゲットのエントリの ID を、そのコレクションのテーブルの列に保持し、管理パネルでは設定できないフィールドオプションでターゲットのコレクションを指定していました。

参照フィールドは現在、リレーションに支えられたエントリピッカーであり、そのリンクはコレクションのテーブルの外に保存されます。更新すると、ターゲットのコレクションを指定していた各参照フィールドが新しいリレーションにバインドされ、その列にあるエントリ ID がリンクとしてコピーされるため、フィールドは選択内容がそのままのピッカーになります。列はそのまま残り、更新によって削除されるものはありません。

次のフィールドは、バインドされないままになります。

• ターゲットのコレクションを指定していない、またはすでに存在しないコレクションを指定している
• 検索可能またはインデックス付きとしてマークされている
• リレーションのスラグ {collection}_{field} が必要で、そのスラグがすでに使われている
• 同じエントリの異なるロケールで、異なるエントリを選択している（どのエントリでも対象）

最後の条件は、リンクが保存される場所に関するものです。リンクはエントリの翻訳グループに属するため、1 つの選択がそのすべての翻訳で共有されますが、古い列はロケールごとでした。ロケール間で食い違っているフィールドには、引き継ぐべき単一の選択がありません。それらを統合すると、各ロケールに他のロケールのエントリを渡すことになり、1 つのロケールの答えを選ぶと残りが失われます。そのため、更新はそのフィールドをそのままにし、両方の値を列から読み取れるようにしておきます。

食い違いに見えても、そうではない場合が 2 つあります。1 つのエントリについて、各ロケールが自身の翻訳を指定している場合は、そのエントリを 1 回選択したことになるため、更新はフィールドをバインドし、リンクは各ロケール自身のバージョンに解決されます。何も選択していないロケールは、他のどのロケールとも矛盾しないため、更新はフィールドをバインドし、グループの 1 つの選択が、空のものを含むすべての翻訳に適用されます。

バインドされていないフィールドは、従来どおりに動作し続けます。その列にはエントリ ID が保持され、値は保存と読み込みができ、フィールドはインデックス付けやコンテンツリストのフィルターとしても引き続き使用できます。エントリエディターでは、ピッカーではなくテキストボックスとして表示されます。

何をすべきか？

参照フィールドを持つ各コレクションで、エントリを開きます。ピッカーとして表示されるフィールドには、何も必要ありません。まだテキストボックスとして表示されるフィールドについては、リレーションがないフィールドを束縛するに従ってください。これによりリレーションが作成され、フィールドに保存されている ID がリンクとしてコピーされます。複数ロケールのサイトでは、バインドすると全翻訳に対して 1 つの選択が保持されるため、バインドする前に、各翻訳がどのエントリを指すべきかを決めておいてください。

更新後にサイトが壊れた場合

• ビルドが失敗する、またはご自身のページがランタイムでエラーになる場合: スキップしたバージョンの、Breaking と表示されたリリースエントリを読み、そこに記載された変更を行ってください。
• プラグインが読み込めない場合: そのプラグイン自身のリリースエントリと、サイトのプラグインをアップグレードを読んでください。
• エラーが Astro の API または @astrojs/* パッケージを挙げている場合: EmDash には Astro 6 以降が必要です。astro とその公式インテグレーションをまとめて更新する方法は、Astro のアップグレードガイドで説明されています。
• 以前のリリースに戻すには、対応する以前のパッケージバージョンを再インストールし、そのアーティファクトを再デプロイします。再インストールしても、コアマイグレーションは元に戻りません。以前のアーティファクトが、マイグレーション済みのデータベースを使用できない場合は、トラフィックを停止し、更新前のデータベースとアーティファクトをまとめて復元してください。メディアは、更新で変更された場合にのみ復元します。