※Drupal11の新機能などはこちらの記事を参照

1. アップデート前の準備

1.1 バックアップの徹底

アップデート前には必ず完全なバックアップを取得しましょう。これにより、何か問題が発生した際に元の状態に戻すことができます。

  • データベースのバックアップ
    MySQLやPostgreSQLなど、ご利用のデータベースのバックアップを取得します。たとえば、MySQLの場合は以下のようなコマンドが使えます.mysqldump -u ユーザー名 -p データベース名 > backup.sql
  • ファイルシステムのバックアップ
    サイトのテーマ、モジュール、カスタムコード、アップロードファイルなど、すべてのファイルを圧縮して保存しておくと安心です.tar -czvf drupal_backup.tar.gz /path/to/drupal

1.2 テスト環境の構築

本番環境に直接変更を加えるのはリスクが高いため、必ずステージングまたはローカル環境でテストアップデートを行います。

  • ステージング環境：本番と同じ設定・条件で構築し、アップデート後の動作確認を徹底する。
  • ローカル環境：小規模なサイトの場合、ローカル環境で実験的にアップデートを実施し、カスタムコードの影響やモジュールの互換性をチェックする。

1.3 サーバー環境の確認

Drupal 11は最新のPHPバージョンやデータベースを要求する場合があります。アップデート前に以下を確認してください。

  • PHPバージョン：公式ドキュメントに記載されている推奨バージョンかどうか。
  • 拡張モジュール：必要なPHP拡張モジュールがインストールされているか。
  • サーバー設定：Webサーバー（ApacheやNginx）の設定がDrupal 11に適合しているか。

1.4 モジュールとテーマの互換性の確認

アップデートに伴い、サードパーティ製のモジュールやテーマに互換性問題が生じる可能性があります。

  • 公式サイトやリリースノートの確認：各モジュールの最新リリースやアップデート情報をチェックする。
  • 開発者コミュニティの意見：フォーラムやGitHubのIssueトラッカーで、同じアップデートを試みたユーザーの報告や解決策を確認する。
  • 代替モジュールの検討：互換性が確認できない場合は、代替となるモジュールの利用を検討する。

参照: システム要件

2. アップデート手順の詳細

2.1 事前チェックと計画立案

  • システム要件の確認
    Drupal 11が要求するサーバー要件（PHP、データベース、Webサーバーのバージョンなど）を再確認し、環境が整っているかをチェックします。
  • リリースノートとドキュメントの精読
    Drupal 11のリリースノートに目を通し、変更点や既知の問題、アップデート手順の推奨事項を把握しましょう。

3. 10.3へのアップデート

Drupal 10.2.x またはそれ以前のバージョンで運用されているサイトは、Drupal 11 へアップグレードする前に必ず 10.3.0 以降に更新する必要があります。なぜなら、10.3.0 より前に追加されたすべてのコアアップデートは削除されているためです。もし、モジュールやテーマが削除されている場合は、代わりにそれぞれの貢献プロジェクト（contributed project）を利用してください。

4. 変更された scaffold files の管理

Drupal 10 から Drupal 11 へアップグレードする際、.htaccess などのDrupalコアファイルはすべて変更される可能性があります。もしscaffold files（自動生成されたファイル）に独自の変更を加えている場合は、その変更内容を記録し、アップグレード後に再適用されるよう注意してください。

例えば、Drupal 11.0.x では統計モジュール（Statistics module）のサポートが削除され、代わりに貢献モジュールへ移行されました。この貢献プロジェクトでは独自の .htaccess による保護が提供されています。サイト運営者は、自身のコピーに残っている不要な .htaccess のルールを削除する必要があります。

5. 非推奨となったDrupalコアのモジュールおよびテーマの整理

Drupal 10 ではいくつかのコアモジュールおよびテーマが非推奨となっており、Drupal 11 では削除されます。詳細は「Deprecated and obsolete extensions」を参照してください。

対象となるものには、Actions UI、Activity Tracker、Book、Forum、Statistics、Tour モジュールが含まれます。

また、Single Directory Components (SDC) および Help Topics モジュールは、機能がコアまたはコアモジュールへ移行されたため、不要となっています。

対応方法としては、Drupal 10 の段階で非推奨モジュールの使用を中止するか、もしくはコードを Drupal 11 にアップグレードする前に、該当拡張の貢献バージョンをインストールする方法があります。

6. 貢献モジュールおよびプロジェクトのアップデート

すべての貢献モジュール・プロジェクトを最新の状態に更新し、Drupal 11 との互換性があることを確認してください。なお、これらのモジュールはDrupal 10.3 以降のサイトでも引き続き動作します。

6.1 Upgrade Status を利用した互換性チェックとアップデート

Upgrade Status モジュールを使って、各貢献モジュールやプロジェクトの Drupal 11 互換性をチェックしてください。互換性のレポートを実行し、その結果に応じて、Composer を使ってモジュールの更新を行います。

6.2 Composer での更新

最新の互換バージョンに更新する最も簡単な方法は、composer update ではなく composer require を使うことです。これにより、composer.json に設定された既存のバージョン制約を無視して更新できます。
例:

composer require drupal/webform:^6.2 --no-update

6.3 互換性が確認できない場合の対応

  • Upgrade Status モジュールは非常に有用ですが、完璧ではありません。互換性が不明なモジュールについては、保守者が支援を必要とするものかを手動で確認し、Composer を使って最新の互換バージョンを要求してください。
  • モジュール・プロジェクトの issue キューを確認し、Drupal 11 互換のパッチが存在する場合は、そのパッチを適用して更新します。
  • もし Drupal 11 互換バージョンやパッチが存在しない場合は、モジュール保守者と協力して、互換バージョンのリリースを促してください。
  • 特定のモジュールが Drupal 11 専用となっている場合は、composer.json 内でバージョン指定を、Drupal 10 用と Drupal 11 用の両方を許容するように変更することが可能です。
    例: "drupal/linkit": "^6.1" を "drupal/linkit": "^6.1 || ^7.0" に変更

7. Upgrade Status と Drupal Rector を用いたカスタムモジュール・テーマのアップデート

もしカスタムモジュールやテーマを使用している場合は、Drupal 10 で非推奨となり、Drupal 11 で削除されるコードを置き換える必要があります。

  • Upgrade Status の利用
    これにより、非推奨のコード箇所を特定します。
  • Drupal Rector の活用
    自動変換ツールである Drupal Rector を使って、コードを Drupal 11 互換に更新してください。

7.1 オプション：Upgrade Status のアンインストール

貢献モジュールとカスタムコードの両方がDrupal 11 互換になったと確認できたら、必要に応じて Upgrade Status モジュールをアンインストールしても構いません。
例:

drush pm:uninstall upgrade_status -y composer remove drupal/upgrade_status --no-update

※ Upgrade Status 自体は Drupal 11 互換となっているため、必ずしも削除する必要はありません。

7.2 オプション：Drush の削除

一部のユーザーは、コアアップデートプロセス中の潜在的な競合を避けるため、アップグレード前に一時的に Drush を削除することを好みます。アップグレード後、Drush は再インストール可能です。
※ただし、Drush を削除すると、通常 Drush で実行しているタスクを他の方法で実施する必要があります。

8. Drupal 11 へのアップグレード

Drupal サイトのルートディレクトリ（composer.json のある場所）から、以下の手順を実行してください。以下は、Drupal 10.3.x から Drupal 11.x へのアップグレード手順の一例です。必要に応じてバージョン番号を調整してください。

8.1 一時的な書き込み権限の付与

保護されたファイルやディレクトリに一時的に書き込み権限を付与します:

chmod 777 web/sites/default chmod 666 web/sites/default/*settings.php chmod 666 web/sites/default/*services.yml

8.2 コア推奨パッケージのバージョン更新

相互依存関係による問題を避けるため、--no-update オプションを使用して次のコマンドを実行します:

composer require 'drupal/core-recommended:^11' \                 'drupal/core-composer-scaffold:^11' \                 'drupal/core-project-message:^11' --no-update

  • 注意: もし composer.json に drupal/core が個別に記載されている場合は、以下のコマンドで削除してください.composer remove drupal/core --no-update
  • drupal/core-dev をインストールしている場合は:composer require 'drupal/core-dev:^11' --dev --no-update
  • Drush をインストールしている場合（推奨バージョンを確認）:composer require 'drush/drush:^13' --no-update

8.3 コード更新のテスト実行

実際の更新前に、--dry-run オプションを使ってテスト実行を行います:

composer update --dry-run

エラーが発生した場合は、エラー内容に従って対処し、再度テスト実行してください。
（コアとその依存関係のみを更新する場合は、以下のコマンドも利用できます）

composer update "drupal/core-*" drush/drush --with-all-dependencies --dry-run

8.4 実際のコード更新の実行

テスト実行で問題がなければ、以下のコマンドで実際の更新を行います:

composer update

8.5 インストール確認

composer update がエラーなく完了したら、以下のコマンドで composer install が問題なく実行されるか確認します。
これにより、他の開発者やデプロイスクリプトが新しい依存関係のインストール時にエラーを起こさないことが保証されます:

composer install

エラーがなく、「Nothing to install, update or remove」と表示されれば正常です。

8.6 データベース更新

コード更新後、保留中のデータベース更新を適用します。
ブラウザで /update.php にアクセスするか、Drush を使用してください:

drush updatedb:status drush updatedb

エラーが発生した場合は、問題が解決するまで更新を再実行してください。

8.7 書き込み権限の復元

アップグレード完了後、sites/default ディレクトリの権限を元に戻します:

chmod 755 web/sites/default chmod 644 web/sites/default/*settings.php chmod 644 web/sites/default/*services.yml

9. アップグレード後のタスク

アップグレードが完了したら、以下の作業を実施してサイトの安定性と整合性を確認してください。

9.1 設定のエクスポート

構成管理を利用している場合、アップグレードによってデータベース更新や YML プロパティの順序変更により設定が上書きされる可能性があります。

  • git diff を実行して変更内容を確認し、問題がなければ設定をエクスポートしコミットしてください。

9.2 PHPCS の実行

Drupal のコーディング標準が更新されている可能性があるため、PHPCS を実行して自動修正および手動での修正を行ってください。

9.3 テストの実施

PHPUnit や Behat などのテストを実行し、サイトの機能が正しく動作しているか確認してください。

9.4 サイト機能の手動テスト

  • ログの監視:
    drush watchdog:tail などでエラーログを監視しながら、サイトの各機能（フォーム送信、ログイン、カスタム機能など）の動作を確認してください。
  • ブラウザでの検証:
    サイトをブラウザで表示し、各ページの表示、フォーム送信、ログイン、カスタム機能などを十分にテストしてください。
  • データベース更新や cron の実行:
    以下のコマンドでデータベース更新や cron を実行し、エラーがないか確認してください:drush updatedb --yes drush cron

10. 共通の問題と対処法

10.1 「Your requirements could not be resolved to an installable set of packages」というエラー

  • このエラーが発生した場合、Drupal コア更新のためにプロジェクト内の他の依存関係も更新する必要があります。
    次のコマンドで、composer.json に設定された現在のバージョン制約をリセットしながら、すべての依存関係を再度 require してください:

    composer show --no-dev --direct --name-only | xargs composer require --no-update

  • また、依存関係の一覧を表示するには以下のコマンドを使用し、必要に応じてバージョン指定を追加します:

    composer show --no-dev --direct --name-only | xargs

    例えば、Drupal コアの RC やアルファ版でしか互換性がない場合は、drupal/native_lazy_loading:@RC や drupal/menu_breadcrumb:@alpha などの指定を追加してください。
    その後、すべての依存関係を含めた状態で以下のコマンドを実行します:

    composer require --update-with-dependencies [依存関係リスト]

  • さらに、依然としてエラーが解消されない場合は、Drupal モジュールの場合、プロジェクトページを確認し、Drupal 11 と互換性のあるバージョンを明示的に require してください。
    例:

    composer require drupal/MODULE_NAME:^2.0.0-rc1 --no-update

  • 依然として互換性のあるバージョンが存在しない場合は、「もしモジュールに Drupal 11 互換版が存在しない場合」のセクションを参照してください。

  • また、次のコマンドを実行することで、Drupal 11 へのアップグレードを妨げている依存関係の一覧を確認できます:

    composer why-not drupal/core ^11

    これらの作業を繰り返し、エラーが解消されるまで Drupal 11 互換のモジュールバージョンを require してください。

10.2 Composer パッチが再適用されない問題

  • cweagans/composer-patches を使用してパッチを適用している場合、一部のパッチが適用されなくなることがあります。
    もしパッチが Drupal コアまたは貢献モジュールにコミットされ、問題が解決済みであれば、composer.json から削除してください。新しいパッチが必要な場合は、composer.json を更新して新しいパッチのリンクを指定してください。

10.3 ロックファイルが最新の変更と同期していない

  • 「Warning: The lock file is not up to date with the latest changes in composer.json」という警告が出た場合、composer.lock ファイルと vendor フォルダを削除し、再度 composer update を実行することで解決する場合があります。

10.4 モジュールに Drupal 11 互換版が存在しない場合

  • 既存のアップデート試行の確認:
    Drupal 11 互換に関する既存の issue や議論を検索し、すでにパッチや解決策が進行中でないか確認してください。
  • Drupal 11 互換タスクの作成:
    Gitlab CI を導入するなどして、互換性の問題のデバッグを促進してください。
  • Project update working group (PUWG) との連携:
    • Drupal Slack ワークスペースの #project-update-working-group チャンネルに参加し、質問や情報共有を行ってください。
    • また、Drupal.org の PUWG issue キュー（https://www.drupal.org/project/puwg）に新たな issue を作成することも可能です。

11. 注意点とトラブルシューティング

11.1 互換性の問題とAPI変更

  • 非推奨APIの対応：
    Drupal 11では、いくつかのAPIが変更・削除されています。カスタムコードでエラーが発生した場合は、最新のAPI仕様に合わせてコードを更新してください。
  • Contribモジュールの依存関係：
    一部モジュールはDrupal 11に対応していない場合があります。問題が発生した場合は、公式フォーラムやIssueトラッカーを参考に、パッチの適用やモジュールの一時的な無効化を検討します。

11.2 ロールバックプランの策定

  • バックアップからの復元
    万が一、アップグレード後に重大な問題が発生した場合、取得したバックアップから速やかに元の状態に戻せるよう、復元手順を事前に確認しておくことが大切です。
  • Gitのブランチ切り替え
    Gitで管理している場合は、アップグレード前のブランチに戻すことで迅速にロールバックが可能です.git checkout main git reset --hard <アップデート前のコミットID>

11.3 コミュニティと公式ドキュメントの活用

  • DrupalフォーラムやSlack などで同様のアップグレード事例を調査し、問題解決のヒントを得る。
  • 公式ドキュメント（アップグレード手順）には最新の情報と注意点が記載されているため、随時参照することが重要です。

12. まとめ

Drupal 10からDrupal 11へのアップグレードは、最新機能の活用やパフォーマンス、セキュリティの強化という大きなメリットを提供します。
しかし、アップグレードには以下の点に注意が必要です：

  • バックアップとテスト環境の構築
  • サーバー環境および依存関係の確認
  • Composerを用いた確実なコアアップデート
  • データベース更新、キャッシュクリア、機能テストの実施
  • モジュール・テーマの互換性チェックと、トラブルシューティングの準備

公式ドキュメントの手順を参考にしつつ、事前の準備と綿密な検証を実施することで、安全かつ効率的なアップグレードが実現できます。これにより、新たなDrupal 11の機能を最大限に活用し、サイト運営のさらなる進化へと繋げることができるでしょう。

弊社では既存サイトのDrupal 11へのアップデート作業のご支援も行っておりますので、お困りの方はお気軽にお問い合わせください。

参考: How to upgrade from Drupal 10 to Drupal 11 | Drupal.org