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。