drupal-update

Drupal モジュールの更新

自動スナップショット、インテリジェントな更新処理、包括的な変更履歴の生成により、DDEV 環境で Drupal モジュールを安全に更新します。

クイックスタート

ユーザーからモジュールの更新を依頼された場合：

1. 安全スナップショットを作成する
2. セキュリティ更新を確認し、自動的に適用する
3. semver で安全なすべてのバージョンを自動更新する
4. メジャーバージョンの更新を確認する
5. メジャー更新が現在の Drupal コアと互換性があるか確認する
6. 互換性のあるメジャー更新についてユーザーに確認する
7. 確認済みのメジャー更新を適用する
8. データベースを更新し、設定をエクスポートする
9. すべての変更を含む変更履歴を生成する

スクリプトパスの規則

このスキル全体で、[skill-directory] はこのスキルがインストールされている場所を指します。一般的な場所は次のとおりです。

• プロジェクトのスキルディレクトリ
• 個人用のスキルディレクトリ
• カスタムスキルディレクトリ

変更履歴取得スクリプトを実行する際は、[skill-directory] をお使いのシステム上のこのスキルの実際のパスに置き換えてください。

事前確認チェックリスト

更新を開始する前に、このチェックリストをコピーしてください。

Update Progress:
- [ ] Verify DDEV environment is running
- [ ] Create snapshot for rollback
- [ ] Check for security updates
- [ ] Run automatic composer updates
- [ ] Review major version updates available
- [ ] Check compatibility for major updates
- [ ] Apply confirmed major updates
- [ ] Run database updates (drush updb)
- [ ] Export configuration (drush cex)
- [ ] Clear caches
- [ ] Generate changelog
- [ ] Verify site functionality

手順ごとのワークフロー

ステップ 1：環境を確認する

DDEV が実行中か確認します。

ddev describe

実行中でない場合は、起動します。

ddev start

ステップ 2：安全スナップショットを作成する

更新の前に必ずスナップショットを作成します。

ddev snapshot --name=pre-update-$(date +%Y%m%d-%H%M%S)

後でロールバックの手順を案内できるよう、スナップショット名を控えてください。

ステップ 3：セキュリティ更新（自動適用）

セキュリティの脆弱性を確認します。

ddev composer audit

脆弱性が見つかった場合：セキュリティ更新は確認を求めずに自動適用されます。見つかったセキュリティ上の問題と、修正されることをユーザーに伝えてください。

脆弱性が見つからなかった場合：次のステップに進みます。

ステップ 4：自動更新

composer update を実行して、semver で安全なすべての更新に対応します。

ddev composer update

次の項目が自動更新されます。

• パッチバージョン（例：3.6.2 → 3.6.3）
• 制約の範囲内のマイナーバージョン（例：制約が ^3.6 の場合、3.6.0 → 3.7.0）

出力を確認し、次の点をチェックします。

• 更新されたパッケージの数
• 警告やエラーの有無
• 依存関係の競合（まれですが発生する可能性があります）

変更履歴に記載する更新済みパッケージを取得する：

composer update の完了後、更新された Drupal モジュールとバージョン変更の一覧を抽出します。更新された各 Drupal モジュールについて、ステップ 11 で変更履歴を取得します。

更新されたパッケージの一覧を取得するには：

# Compare composer.lock before and after, or parse composer update output
# The output shows: "Updating drupal/module (1.0.7 => 1.0.9)"

変更履歴の生成に使う更新一覧を、drupal/[module]: [old_version] → [new_version] の形式で保存します。

ステップ 5：メジャーバージョンの更新を確認する

古くなっている Drupal モジュールをすべて取得します。

ddev composer outdated 'drupal/*' --direct --format=json

JSON 出力を解析し、"latest-status": "update-possible" のモジュールに絞り込みます。これらは、バージョン制約を明示的に変更する必要があるメジャーバージョンの更新です。

メジャー更新の例：

• drupal/anchor_link：2.7.0 → 3.0.3
• drupal/webform：6.2.0 → 7.0.0

ステップ 5.5：現在の Drupal コアとの互換性を確認する

ステップ 5 で見つかったメジャーアップデートごとに、現在の Drupal コアとの互換性を確認します。

現在の Drupal コアのバージョンを取得します：

CORE_VERSION=$(ddev composer show drupal/core --format=json | jq -r '.versions[0]')

各メジャーアップデートについて、利用可能なすべてのバージョンを取得します：

ddev composer show drupal/[module] --all --format=json

JSON を解析して互換性のあるバージョンを見つけます：

出力はバージョンオブジェクトの配列で、各オブジェクトには次の項目が含まれます。

• version：バージョン番号（例：「3.0.0」、「2.5.1」）
• require.drupal/core：コアのバージョン制約（例：「^10.2」、「^11」）
• require.php：PHP のバージョン要件（例：「>=8.1」）

互換性のあるバージョンを見つけるロジック：

1. JSON 出力からすべてのバージョンを解析します
2. 各バージョンについて、現在のコアのバージョンがその require.drupal/core 制約を満たすか確認します
3. 互換性のあるバージョンのうち、最も高いものを見つけます
4. 互換性のある最も高いバージョンが現在インストールされているバージョンより新しい場合は、ユーザーに提示します
5. 最新バージョンが Drupal 11 を必要とする一方で、Drupal 10 を使用している場合は、Drupal 10 と互換性のある最も高いバージョンを見つけます

制約の確認例：

• 現在のコア：10.3.5
• モジュールのバージョン 3.0.0 の要件：^11 → 互換性なし
• モジュールのバージョン 2.5.0 の要件：^10.2 → 互換性あり
• モジュールのバージョン 2.0.0 の要件：^9.5 || ^10 → 互換性あり
• 結果：バージョン 2.5.0 を提案します（互換性のある最も高いバージョン）

制約構文のリファレンス：

• ^10.2 = >=10.2.0 <11.0.0
• ^11 = >=11.0.0 <12.0.0
• ^9.5 || ^10 || ^11 = 複数のバージョンに対応
• >=10.2 = 10.2.0 以降のすべてのバージョン

注： 互換性を確認するときは、モジュールの require.drupal/core 制約と現在の Drupal コアのバージョンを比較します。最新バージョンに互換性がない場合は、利用可能なバージョンを降順に確認し、現在のコアと互換性のある最も高いバージョンを見つけます。

ステップ 6：メジャーアップデートを対話形式で選択する

利用可能なメジャーアップデートごとに、互換性情報を添えてユーザーに提示します。

最新バージョンに互換性がある場合：

Major update available:
- Module: drupal/anchor_link
- Current: 2.7.0
- Latest: 3.0.3 (compatible with current Drupal core)
- Risk: Major version update may contain breaking changes

Update this module? (y/n)

最新バージョンに互換性がない場合は、推奨バージョンを表示します：

Major update available:
- Module: drupal/anchor_link
- Current: 2.7.0
- Latest: 3.0.3 (requires Drupal ^11, not compatible)
- Recommended: 2.9.0 (highest version compatible with Drupal 10.3.5)
- Risk: Major version update may contain breaking changes

Update to version 2.9.0? (y/n)

互換性のあるメジャーバージョンがない場合：

Major update available:
- Module: drupal/anchor_link
- Current: 2.7.0
- Latest: 3.0.3 (requires Drupal ^11, not compatible)
- Warning: No compatible major version found for current Drupal core
- Note: Consider upgrading Drupal core first, or skip this update

Skip this update? (y/n)

ユーザーが承認したモジュールと、それぞれにインストールする互換性のあるバージョンのリストを作成します。

ステップ 7：メジャーアップデートを適用する

承認されたメジャーアップデートごとに、ステップ 5.5 で判定した互換性のあるバージョンを使用します。

ddev composer require drupal/[module]:^[compatible-version] --update-with-all-dependencies

例：

互換性のあるバージョンが 2.9.0 の場合：

ddev composer require drupal/anchor_link:^2.9 --update-with-all-dependencies

最新バージョン（3.0.3）に互換性がある場合：

ddev composer require drupal/anchor_link:^3.0 --update-with-all-dependencies

注： 常にステップ 5.5 で判定した互換性のあるバージョンを使用してください。必ずしも最新バージョンとは限りません。これにより、現在の Drupal コアのバージョンでアップデートが動作することを保証できます。

エラーへの対処：依存関係の競合によりメジャーアップデートに失敗した場合：

1. エラーをユーザーに表示します
2. 他のアップデートを続行するか、ユーザーに尋ねます
3. 失敗したアップデートを変更履歴に記録します
4. エラーが互換性の問題を示している場合は、ステップ 5.5 で互換性を再確認します

ステップ 8：データベースを更新する

データベースを更新し、スキーマの変更を適用します。

ddev drush updb -y

エラーを監視します：データベースの更新に失敗した場合は、直ちに停止してユーザーに知らせます。

ステップ 9：設定をエクスポートする

有効な設定を同期ディレクトリにエクスポートします。

ddev drush config:export -y

エクスポート先を確認します。

ddev drush status --field=config-sync

ステップ 10：キャッシュをクリアする

変更を反映させるため、すべてのキャッシュをクリアします。

ddev drush cache:rebuild

ステップ 11：変更履歴を生成する

すべてのアップデート（セキュリティ、マイナー、パッチ、メジャーバージョン）のリリースノートを取得して、変更履歴ファイルを作成します。

更新した Drupal モジュールごとに、変更履歴を取得します：

ddev exec php [skill-directory]/scripts/fetch_changelog.php drupal/[module] [old_version] [new_version]

すべてのアップデートを処理します：

1. セキュリティアップデート（ステップ 3）：適用した各セキュリティアップデートの変更履歴を取得します
2. 自動アップデート（ステップ 4）：各マイナー／パッチアップデートの変更履歴を取得します
3. メジャーアップデート（ステップ 7）：各メジャーバージョンアップデートの変更履歴を取得します

複数のアップデートの例：

# Security update
ddev exec php [skill-directory]/scripts/fetch_changelog.php drupal/admin_toolbar 3.6.2 3.6.3

# Minor update
ddev exec php [skill-directory]/scripts/fetch_changelog.php drupal/admin_audit_trail 1.0.7 1.0.9

# Major update
ddev exec php [skill-directory]/scripts/fetch_changelog.php drupal/anchor_link 2.7.0 3.0.3

PHP スクリプトを利用できない場合は、次の構成で UPDATES-[DATE].md を手動で作成します。

# Drupal Module Updates - [YYYY-MM-DD]

## Security Updates (Auto-Applied)
[List security updates that were applied]

## Automatic Updates (composer update)
[List all packages updated by composer update - includes patch and minor versions]

For each update, include:
- drupal/admin_audit_trail: 1.0.7 → 1.0.9
  - Release: https://www.drupal.org/project/admin_audit_trail/releases/1.0.9
  - Changes: [Key changes from release notes fetched via fetch_changelog.php script]

## Major Version Updates
[List major updates applied via composer require]
- drupal/anchor_link: 2.7.0 → 3.0.3
  - Command: `composer require drupal/anchor_link:^3.0`
  - Release: https://www.drupal.org/project/anchor_link/releases/3.0.3
  - Changes: [Key changes and breaking changes]

## Post-Update Tasks Completed
- [x] Database updates applied (drush updb)
- [x] Configuration exported (drush cex)
- [x] Caches cleared (drush cr)

## Rollback Instructions
To rollback these updates:
\`\`\`bash
ddev snapshot restore --name=pre-update-[timestamp]
\`\`\`

検証とテスト

更新が完了したら：

エラーを確認します：

ddev drush watchdog:show --count=20 --severity=Error

設定のステータスを確認します：

ddev drush config:status

エクスポートされていない設定変更がある場合は、確認します：

ddev drush config:export --diff

重要な機能をテストします：

次の項目をテストするようユーザーに伝えます：

• ユーザー認証
• コンテンツの作成・編集
• フォームと送信
• カスタム機能

エラー処理

Composer の更新に失敗した場合

composer update が失敗した場合：

1. エラーメッセージを確認し、依存関係の競合がないか確認します
2. 失敗した特定のパッケージを更新してみます：

   ddev composer update drupal/[module] --with-all-dependencies
   

3. それでも失敗する場合は、drupal.org で既知の問題を確認します

データベースの更新に失敗した場合

drush updb が失敗した場合：

1. エラーメッセージを慎重に確認します
2. watchdog のログを確認します：ddev drush watchdog:show
3. ロールバックを検討します：ddev snapshot restore --name=[snapshot-name]
4. エラーの詳細をすべて添えて、問題をユーザーに報告します

設定のエクスポートに関する問題

設定のエクスポートで予期しない変更が表示された場合：

1. 差分を確認します：ddev drush config:export --diff
2. 変更が更新による想定どおりのものか確認します
3. 判断に迷う場合は、エクスポートする前にユーザーに確認を依頼します

ロールバック手順

問題が発生した場合：

# List available snapshots
ddev snapshot list

# Restore to pre-update state
ddev snapshot restore --name=pre-update-[timestamp]

# Verify restoration
ddev drush status

ロールバック後：

1. キャッシュをクリアします：ddev drush cr
2. サイトが正常に機能することを確認します
3. 再度更新を試みる前に、問題の原因を調査します

よくあるシナリオ

セキュリティ更新、メジャーバージョンへのアップグレード、互換性の問題、エラーからの復旧など、実際の更新ワークフローの例については、examples.md を参照してください。

追加リソース

composer コマンドのオプション、トラブルシューティングガイド、コマンドのクイックリファレンスについて詳しくは、reference.md を参照してください。