drupal-update

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Drupal Module Updates

Drupal模块更新

Safely update Drupal modules in DDEV environments with automatic snapshots, intelligent update handling, and comprehensive changelog generation.

在DDEV环境中安全更新Drupal模块，支持自动快照、智能更新处理和全面的变更日志生成。

Quick Start

快速开始

When the user requests a module update:

Create safety snapshot
Check and apply security updates automatically
Run automatic updates for all semver-safe versions
Check for major version updates
Check compatibility for major updates with current Drupal core
Ask user about compatible major updates
Apply confirmed major updates
Run database updates and export configuration
Generate changelog with all changes

当用户请求模块更新时：

创建安全快照
自动检查并应用安全更新
对所有符合语义化版本安全规则的版本执行自动更新
检查主要版本更新
检查主要版本更新与当前Drupal核心的兼容性
询问用户是否更新兼容的主要版本
应用已确认的主要版本更新
运行数据库更新并导出配置
生成包含所有变更的变更日志

Script Path Convention

脚本路径约定

Throughout this skill,

[skill-directory]

refers to the location where this skill is installed. Common locations include:

Project skills directory
Personal skills directory
Custom skills directory

Replace

[skill-directory]

with the actual path to this skill on your system when running the changelog fetch script.

在本技能中，

[skill-directory]

指的是本技能的安装位置。常见位置包括：

运行变更日志获取脚本时，请将

[skill-directory]

替换为系统中本技能的实际路径。

Pre-Flight Checklist

预更新检查清单

Before starting updates, copy this checklist:

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

开始更新前，请复制以下检查清单：

Update Progress:
- [ ] 验证DDEV环境正在运行
- [ ] 创建用于回滚的快照
- [ ] 检查安全更新
- [ ] 运行自动composer更新
- [ ] 查看可用的主要版本更新
- [ ] 检查主要版本更新的兼容性
- [ ] 应用已确认的主要版本更新
- [ ] 运行数据库更新（drush updb）
- [ ] 导出配置（drush cex）
- [ ] 清除缓存
- [ ] 生成变更日志
- [ ] 验证站点功能

Step-by-Step Workflow

分步工作流

Step 1: Verify Environment

步骤1：验证环境

Check DDEV is running:

bash

ddev describe

If not running, start it:

bash

ddev start

检查DDEV是否正在运行：

bash

ddev describe

如果未运行，启动它：

bash

ddev start

Step 2: Create Safety Snapshot

步骤2：创建安全快照

Always create a snapshot before updates:

bash

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

Store the snapshot name for rollback instructions later.

更新前务必创建快照：

bash

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

记录快照名称，以便后续回滚使用。

Step 3: Security Updates (Auto-Apply)

步骤3：安全更新（自动应用）

Check for security vulnerabilities:

bash

ddev composer audit

If vulnerabilities found: Security updates are automatically applied without asking. Inform the user which security issues were found and will be fixed.

If no vulnerabilities: Proceed to next step.

检查安全漏洞：

bash

ddev composer audit

如果发现漏洞：将自动应用安全更新，无需确认。告知用户发现的安全问题及修复情况。

如果未发现漏洞：进入下一步。

Step 4: Automatic Updates

步骤4：自动更新

Run composer update to handle all semver-safe updates:

bash

ddev composer update

This automatically updates:

Patch versions (e.g., 3.6.2 → 3.6.3)
Minor versions within constraints (e.g., 3.6.0 → 3.7.0 if constraint is ^3.6)

Monitor the output for:

Number of packages updated
Any warnings or errors
Dependency conflicts (rare but possible)

Capture updated packages for changelog:

After

composer update

completes, extract the list of updated Drupal modules and their version changes. For each updated Drupal module, you'll fetch the changelog in Step 11.

To get the list of updated packages:

bash

undefined

运行composer update处理所有符合语义化版本安全规则的更新：

bash

ddev composer update

此命令会自动更新：

补丁版本（例如：3.6.2 → 3.6.3）
约束范围内的次要版本（例如：如果约束为^3.6，则从3.6.0更新到3.7.0）

监控输出内容：

更新的包数量
任何警告或错误
依赖冲突（罕见但可能发生）

捕获更新的包以生成变更日志：

composer update

完成后，提取所有更新的Drupal模块及其版本变更。对于每个更新的Drupal模块，将在步骤11中获取其变更日志。

获取更新的包列表：

bash

undefined

Compare composer.lock before and after, or parse composer update output

比较更新前后的composer.lock，或解析composer update的输出

The output shows: "Updating drupal/module (1.0.7 => 1.0.9)"

输出格式示例："Updating drupal/module (1.0.7 => 1.0.9)"


Store the list of updates in format: `drupal/[module]: [old_version] → [new_version]` for changelog generation.


以`drupal/[module]: [old_version] → [new_version]`的格式存储更新列表，用于生成变更日志。

Step 5: Check for Major Version Updates

步骤5：检查主要版本更新

Get all outdated Drupal modules:

bash

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

Parse the JSON output and filter for modules with

"latest-status": "update-possible"

. These are major version updates that require explicit version constraint changes.

Example major updates:

```
drupal/anchor_link
```
: 2.7.0 → 3.0.3
```
drupal/webform
```
: 6.2.0 → 7.0.0

获取所有过时的Drupal模块：

bash

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

Step 5.5: Verify Compatibility with Current Drupal Core

步骤5.5：验证与当前Drupal核心的兼容性

For each major update found in Step 5, verify compatibility with current Drupal core:

Get current Drupal core version:

bash

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

For each major update, get all available versions:

bash

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

Parse the JSON to find compatible versions:

The output is an array of version objects, each containing:

```
version
```
: The version number (e.g., "3.0.0", "2.5.1")
```
require.drupal/core
```
: Core version constraint (e.g., "^10.2", "^11")
```
require.php
```
: PHP version requirement (e.g., ">=8.1")

Logic for finding compatible version:

Parse all versions from the JSON output
For each version, check if its
```
require.drupal/core
```
constraint is satisfied by current core version
Find the highest compatible version
If the highest compatible version is greater than the currently installed version, present it to the user
If the latest version requires Drupal 11 but we have Drupal 10, find the highest Drupal 10-compatible version

Example constraint checking:

Current core:
```
10.3.5
```
Module version 3.0.0 requires:
```
^11
```
→ NOT compatible
Module version 2.5.0 requires:
```
^10.2
```
→ Compatible
Module version 2.0.0 requires:
```
^9.5 || ^10
```
→ Compatible
Result: Offer version 2.5.0 (highest compatible)

Constraint syntax reference:

```
^10.2
```
=
```
>=10.2.0 <11.0.0
```
```
^11
```
=
```
>=11.0.0 <12.0.0
```
```
^9.5 || ^10 || ^11
```
= Multiple versions supported
```
>=10.2
```
= Any version from 10.2.0 onwards

Note: When checking compatibility, compare the module's

require.drupal/core

constraint against the current Drupal core version. If the latest version is incompatible, iterate through available versions (sorted descending) to find the highest version that is compatible with the current core.

对于步骤5中发现的每个主要版本更新，验证其与当前Drupal核心的兼容性：

获取当前Drupal核心版本：

bash

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

对于每个主要版本更新，获取所有可用版本：

bash

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"）

查找兼容版本的逻辑：

解析JSON输出中的所有版本
对于每个版本，检查其
```
require.drupal/core
```
约束是否满足当前核心版本
找到最高的兼容版本
如果最高兼容版本高于当前安装版本，将其呈现给用户
如果最新版本需要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核心版本进行比较。如果最新版本不兼容，则按降序遍历可用版本，找到与当前核心兼容的最高版本。

Step 6: Interactive Major Update Selection

步骤6：交互式主要版本更新选择

For each major update available, present to the user with compatibility information:

If the latest version is compatible:

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)

If the latest version is NOT compatible, show recommended version:

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)

If no compatible major version exists:

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)

Build a list of modules the user confirms, along with the compatible version to install for each.

对于每个可用的主要版本更新，向用户呈现兼容性信息：

如果最新版本兼容：

有可用的主要版本更新：
- 模块：drupal/anchor_link
- 当前版本：2.7.0
- 最新版本：3.0.3（与当前Drupal核心兼容）
- 风险：主要版本更新可能包含破坏性变更

是否更新此模块？(y/n)

如果最新版本不兼容，显示推荐版本：

有可用的主要版本更新：
- 模块：drupal/anchor_link
- 当前版本：2.7.0
- 最新版本：3.0.3（需要Drupal ^11，不兼容）
- 推荐版本：2.9.0（与Drupal 10.3.5兼容的最高版本）
- 风险：主要版本更新可能包含破坏性变更

是否更新到版本2.9.0？(y/n)

如果没有兼容的主要版本：

有可用的主要版本更新：
- 模块：drupal/anchor_link
- 当前版本：2.7.0
- 最新版本：3.0.3（需要Drupal ^11，不兼容）
- 警告：未找到与当前Drupal核心兼容的主要版本
- 说明：考虑先升级Drupal核心，或跳过此更新

是否跳过此更新？(y/n)

收集用户确认更新的模块列表，以及每个模块要安装的兼容版本。

Step 7: Apply Major Updates

步骤7：应用主要版本更新

For each confirmed major update, use the compatible version determined in Step 5.5:

bash

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

Examples:

If compatible version is 2.9.0:

bash

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

If latest version (3.0.3) is compatible:

bash

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

Note: Always use the compatible version determined in Step 5.5, not necessarily the latest version. This ensures the update will work with the current Drupal core version.

Handle errors: If a major update fails due to dependency conflicts:

Show the error to the user
Ask if they want to continue with other updates
Document the failed update in the changelog
If the error indicates incompatibility, re-check compatibility in Step 5.5

对于每个确认的主要版本更新，使用步骤5.5中确定的兼容版本：

bash

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

示例：

如果兼容版本是2.9.0：

bash

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

如果最新版本（3.0.3）兼容：

bash

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

注意： 务必使用步骤5.5中确定的兼容版本，而非最新版本。这确保更新能与当前Drupal核心版本兼容。

错误处理：如果主要版本更新因依赖冲突失败：

向用户显示错误信息
询问用户是否继续进行其他更新
在变更日志中记录失败的更新
如果错误表明不兼容，重新执行步骤5.5的兼容性检查

Step 8: Database Updates

步骤8：数据库更新

Run database updates to apply schema changes:

bash

ddev drush updb -y

Monitor for errors: If database updates fail, stop immediately and inform the user.

运行数据库更新以应用架构变更：

bash

ddev drush updb -y

监控错误：如果数据库更新失败，立即停止并告知用户。

Step 9: Export Configuration

步骤9：导出配置

Export active configuration to sync directory:

bash

ddev drush config:export -y

Verify the export location:

bash

ddev drush status --field=config-sync

将活跃配置导出到同步目录：

bash

ddev drush config:export -y

验证导出位置：

bash

ddev drush status --field=config-sync

Step 10: Clear Caches

步骤10：清除缓存

Clear all caches to ensure changes take effect:

bash

ddev drush cache:rebuild

清除所有缓存以确保变更生效：

bash

ddev drush cache:rebuild

Step 11: Generate Changelog

步骤11：生成变更日志

Create a changelog file by fetching release notes for all updates (security, minor, patch, and major versions).

For each updated Drupal module, fetch the changelog:

bash

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

Process all updates:

Security updates (from Step 3): Fetch changelog for each security update applied
Automatic updates (from Step 4): Fetch changelog for each minor/patch update
Major updates (from Step 7): Fetch changelog for each major version update

Example for multiple updates:

bash

undefined

通过获取所有更新（安全更新、次要版本、补丁版本和主要版本）的发布说明，创建变更日志文件。

对于每个更新的Drupal模块，获取其变更日志：

bash

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

处理所有更新：

安全更新（来自步骤3）：为每个应用的安全更新获取变更日志
自动更新（来自步骤4）：为每个次要/补丁更新获取变更日志
主要版本更新（来自步骤7）：为每个主要版本更新获取变更日志

多更新示例：

bash

undefined

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


**If the PHP script is unavailable**, manually create `UPDATES-[DATE].md` with this structure:

```markdown

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


**如果PHP脚本不可用**，手动创建`UPDATES-[DATE].md`，格式如下：

```markdown

Drupal Module Updates - [YYYY-MM-DD]

Drupal模块更新 - [YYYY-MM-DD]

Security Updates (Auto-Applied)

安全更新（自动应用）

[List security updates that were applied]

[列出所有已应用的安全更新]

Automatic Updates (composer update)

自动更新（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]

[列出所有通过composer update更新的包 - 包含补丁和次要版本]

对于每个更新，包含：

drupal/admin_audit_trail: 1.0.7 → 1.0.9
- 发布地址：https://www.drupal.org/project/admin_audit_trail/releases/1.0.9
- 变更内容：[通过fetch_changelog.php脚本获取的发布说明中的关键变更]

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]

[列出所有通过composer require应用的主要版本更新]

drupal/anchor_link: 2.7.0 → 3.0.3
- 命令：
```
composer require drupal/anchor_link:^3.0
```
- 发布地址：https://www.drupal.org/project/anchor_link/releases/3.0.3
- 变更内容：[关键变更和破坏性变更]

Post-Update Tasks Completed

已完成的更新后任务

Database updates applied (drush updb)
Configuration exported (drush cex)
Caches cleared (drush cr)

应用数据库更新（drush updb）
导出配置（drush cex）
清除缓存（drush cr）

Rollback Instructions

回滚说明

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

undefined

如需回滚这些更新： ```bash ddev snapshot restore --name=pre-update-[timestamp] ```

undefined

Validation and Testing

验证与测试

After updates are complete:

更新完成后：

Check for errors:

检查错误：

bash

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

bash

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

Verify configuration status:

验证配置状态：

bash

ddev drush config:status

If there are configuration changes not exported, review them:

bash

ddev drush config:export --diff

bash

ddev drush config:status

如果存在未导出的配置变更，查看详情：

bash

ddev drush config:export --diff

Test critical functionality:

测试关键功能：

Inform the user to test:

User authentication
Content creation/editing
Forms and submissions
Any custom functionality

告知用户测试以下内容：

用户认证
内容创建/编辑
表单与提交
任何自定义功能

Error Handling

错误处理

Composer Update Fails

Composer Update失败

composer update

fails:

Check the error message for dependency conflicts

Try updating specific packages that failed:

bash

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

If still failing, check for known issues on drupal.org

如果

composer update

失败：

检查错误信息中的依赖冲突

尝试单独更新失败的包：

bash

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

如果仍然失败，查看drupal.org上的已知问题

Database Updates Fail

数据库更新失败

drush updb

fails:

Review the error message carefully
Check watchdog logs:
```
ddev drush watchdog:show
```

Consider rolling back:

ddev snapshot restore --name=[snapshot-name]

Report the issue to the user with full error details

如果

drush updb

失败：

仔细查看错误信息
查看监控日志：
```
ddev drush watchdog:show
```

考虑回滚：

ddev snapshot restore --name=[snapshot-name]

向用户报告问题及完整错误详情

Configuration Export Issues

配置导出问题

If configuration export shows unexpected changes:

Review the diff:
```
ddev drush config:export --diff
```
Check if changes are expected from the updates
If uncertain, ask the user to review before exporting

如果配置导出显示意外变更：

查看差异：
```
ddev drush config:export --diff
```
检查变更是否是更新导致的预期结果
如果不确定，询问用户是否在导出前进行审核

Rollback Procedure

回滚流程

If something goes wrong:

bash

undefined

如果出现问题：

bash

undefined

List available snapshots

列出可用快照

ddev snapshot list

Restore to pre-update state

恢复到更新前的状态

ddev snapshot restore --name=pre-update-[timestamp]

Verify restoration

验证恢复结果

ddev drush status


After rollback:
1. Clear caches: `ddev drush cr`
2. Verify site functionality
3. Investigate the issue before attempting updates again

ddev drush status


回滚后：
1. 清除缓存：`ddev drush cr`
2. 验证站点功能
3. 在再次尝试更新前，先排查问题

Common Scenarios

常见场景

For real-world examples of update workflows including security updates, major version upgrades, compatibility issues, and error recovery, see examples.md.

有关包含安全更新、主要版本升级、兼容性问题和错误恢复的真实更新工作流示例，请查看examples.md。

Additional Resources

额外资源

For detailed composer command options, troubleshooting guides, and a quick commands reference, see reference.md.

有关Composer命令选项的详细说明、故障排除指南和快速命令参考，请查看reference.md。