EmDashのアップデート
このページで分かること
- 1.0より前のバージョン番号の決まり（パッチリリースは修正、マイナーリリースは新機能と破壊的変更）と、
emdashと@emdash-cms/cloudflareを同じバージョンで同時に更新すること - 更新前のバックアップとNode.jsのバージョンの確認、
pnpm up --latestによるパッケージの更新、ビルドとローカルでの確認 - デプロイ後の確認と、更新後にサイトが動かなくなったときの対処（元のバージョンに戻してもコアマイグレーションは元に戻らないこと）
このページの目次
このガイドは、サイトの運用者、つまりEmDashで作ったサイトを運用していて、それを新しいリリースにしたい人を対象にしています。emdash パッケージと @emdash-cms/cloudflare を扱います。プラグインのパッケージには専用のガイドサイトのプラグイン更新があり、自分のコレクションとフィールドの変更は運用中サイトのスキーマ変更で扱っています。
リリースとバージョン番号
EmDashはバージョン1.0より前の段階でリリースされており、バージョン番号は次の2つの決まりに従います。
- パッチリリース（たとえば0.35.0から0.35.1）には、バグ修正と小さな改善が含まれます。
- マイナーリリース（たとえば0.35から0.36）には、新機能と、破壊的変更がある場合はその変更が含まれます。破壊的変更には、リリース情報の中で Breaking と印が付けられ、その項目に必要な対応が書かれています。
emdash と @emdash-cms/cloudflare は同時にリリースされ、1つのバージョン番号を共有します。@emdash-cms/cloudflare は、バージョンが完全に一致する emdash に依存するため、2つのパッケージは1回の操作で更新します。@emdash-cms/plugin-forms のようなプラグインのパッケージは独自のバージョン番号を持ち、必要な emdash の最小バージョンを宣言しています。
リリースページには、パッケージとバージョンごとに1つの項目があります。更新の前に、インストール済みのバージョンから更新先のバージョンまでの emdash の項目を読みます。サイトをCloudflareで動かしている場合は、@emdash-cms/cloudflare の同じ範囲の項目も読みます。
やさしい解説
WordPressでは、本体の更新は管理画面の「更新」ボタンで実行できます。EmDashはサイトのプロジェクトが使うnpmのパッケージの1つなので、パッケージのバージョンを上げてビルドし、デプロイし直すことで更新します。EmDashはまだ1.0より前のため、0.35から0.36のような「真ん中の数字」が上がる更新には、サイトのコードの修正が必要な変更（Breaking）が含まれることがあります。そのため、更新の前にGitHubのリリースページで、今のバージョンから更新先までの項目を読みます。
更新の前に
復元できるデータベースのバックアップと、それとは別のメディアストレージのバックアップを取ります。EmDashのJSONエクスポートではサイトを復元できません。また、コアマイグレーションには、運用の中で元に戻す手順がありません。データベースごとに使える復旧ポイントは、バックアップと復旧で説明しています。
サイトをビルドするマシンのNode.jsのバージョンを確認します。Node.jsでデプロイしている場合は、サーバーのバージョンも確認します。対応しているバージョンは、はじめてのEmDashサイト作成に一覧があります。
パッケージを更新する
以下のコマンドは、pnpmと、Cloudflareテンプレートから作ったサイトを前提にしています。Node.jsでデプロイしている場合は、@emdash-cms/cloudflare を除きます。
-
インストール済みのバージョンと、最新のリリースを確認します。
pnpm outdated emdash @emdash-cms/cloudflare -
両方のパッケージを最新のリリースに上げます。
テンプレートから生成した
package.jsonには、^0.35.0のようなキャレットの範囲でパッケージが書かれています。1.0より前のバージョンでは、キャレットの範囲はパッチリリースだけを許可し（0.35.1は許可、0.36.0は許可しない）、オプションを付けないpnpm upはこの範囲の中にとどまります。--latestフラグを付けると、範囲を最新のリリースに書き換えてインストールします。pnpm up --latest emdash @emdash-cms/cloudflarepackage.jsonにあるプラグインのパッケージも、同じコマンドに追加します。 -
サイトをビルドします。
pnpm buildビルドは、インストールしたバージョンのマイグレーションのマニフェストを書き出します。ビルドに失敗した場合は、更新後にサイトが動かなくなった場合を参照してください。
-
ローカルでサイトを起動し、
/_emdash/adminで管理画面を開きます。pnpm devEmDashのインテグレーションは、開発サーバーの起動時に
emdash-env.d.tsを生成します。未適用のコアマイグレーションは、最初のリクエストで実行されます。
やさしい解説
pnpm up --latest emdash @emdash-cms/cloudflare は、package.json に書かれたEmDashのバージョンを最新に書き換えてインストールするコマンドです。--latest を付けないと、^0.35.0 のような書き方の範囲（1.0より前では0.35.xまで）の中でしか上がりません。emdash と @emdash-cms/cloudflare は必ず同じバージョンにそろえる必要があるため、2つを同じコマンドで更新します。
デプロイして確かめる
ビルドは、他の変更と同じ方法でデプロイします。次のコマンドはCloudflareのサイトをデプロイします。Node.jsでデプロイしている場合は、新しいビルドでサーバーのプロセスを再起動します。
pnpm wrangler deploy
実行時のマイグレーションのモードが既定の auto の場合、デプロイしたサイトは最初のリクエストで未適用のコアマイグレーションを適用します。新しいコードがリクエストを受け取る前にマイグレーションを適用し、その後にデプロイしたデータベースを確かめるには、コアDBマイグレーションの手順に従います。その emdash migrate --check コマンドは、デプロイしたデータベースに、インストールしたバージョンから見て未適用または不明なマイグレーションがある場合、0以外の終了コードで終了します。
デプロイ後、管理画面を開き、公開ページを少なくとも1つ読み込み、削除してよいエントリーを編集して公開し、削除してよいメディアファイルをアップロードして取得します。サイトで予約処理やサンドボックス型プラグインを使っている場合は、それらの処理も確かめます。
更新後にサイトが動かなくなった場合
- ビルドに失敗する、または自分で作ったページが実行時にエラーになる：飛ばしたバージョンのリリース情報のうち Breaking と印の付いた項目を読み、そこに書かれた変更を加えます。
- プラグインが読み込まれない：そのプラグイン自身のリリース情報と、サイトのプラグイン更新を読みます。
- エラーにAstroのAPIや
@astrojs/*パッケージの名前が出る：EmDashにはAstro 6以上が必要です。Astroのアップグレードガイドで、astroと公式のインテグレーションをまとめて更新する方法を説明しています。 - 以前のリリースに戻すには、対応する以前のバージョンのパッケージを再インストールし、その成果物を再デプロイします。再インストールしても、コアマイグレーションは元に戻りません。以前の成果物がマイグレーション後のデータベースを使えない場合は、通信を止め、更新前のデータベースと成果物を一緒に復元します。メディアは、更新でメディアが変わった場合にだけ復元します。
やさしい解説
更新後に以前のバージョンへ戻しても、データベースの構造は新しいバージョンに合わせて変更された（コアマイグレーションが適用された）ままです。以前のバージョンがその構造のデータベースで動かない場合は、更新前に取ったデータベースのバックアップと、以前のバージョンのサイトを一緒に戻す必要があります。これが、更新の前に復元できるバックアップを取る理由です。