README

Drainpipe 是一个 composer 包，为 Drupal 站点提供构建工具和测试助手，包括

站点和数据库更新
用于部署到托管提供商的工件打包
自动测试设置
DDEV 集成
持续集成集成

安装

composer config extra.drupal-scaffold.gitignore true
composer config --json extra.drupal-scaffold.allowed-packages "[\"lullabot/drainpipe\", \"lullabot/drainpipe-dev\"]"
composer require lullabot/drainpipe
composer require lullabot/drainpipe-dev --dev

如果使用 DDEV，重启以启用添加的功能

ddev restart

这将创建各种文件，最重要的是在您的仓库根目录下的 Taskfile.yml 文件。 Task 是一个任务运行器/构建工具，旨在比 GNU Make 更简单、更容易使用。由于它用 Go 编写，Task 只是一个二进制文件，没有其他依赖。它也是跨平台的，所有操作都通过相同的 shell 解释器运行。

您可以通过运行 ./vendor/bin/task --list 或在运行 DDEV 时运行 ddev task --list 来查看安装后可用的任务。要获取有关特定任务的信息（例如，它接受哪些参数），您可以运行 task [task name] --summary。

您的 Taskfile.yml 可以使用 JSON Schema 进行验证

curl -O https://taskfile.dev/schema.json
npx ajv-cli validate -s schema.json -d scaffold/Taskfile.yml

请参阅 .github/workflows/validate-taskfile.yml 了解此用法的示例。

💡 If your docroot is not the standard `web/` path, you must create a symlink to it
ln -s web/ docroot

二进制文件

如果您收到类似于 exec format error: ./vendor/bin/task 的错误，那么您可能具有错误的体系结构二进制文件。如果您的体系结构没有正确检测到，请打开一个带有 php -r "echo php_uname('m');" 输出的一个问题，以及有关您的硬件和操作系统的信息。

您可以使用环境变量 DRAINPIPE_PLATFORM 和 DRAINPIPE_PROCESSOR 覆盖平台和处理器。有效的平台值是 linux、darwin 或 windows，处理器是 386、amd64 或 arm64。这些对应于上游依赖项的构建，例如 https://github.com/go-task/task/releases

数据库更新

drupal:update 命令遵循与 'drush deploy' 命令相同的程序，但它在某些情况下会运行配置导入两次，因为在完成之前，导入可能会由于内存耗尽而失败。

drush updatedb --no-cache-clear
drush cache:rebuild
drush config:import || true
drush config:import
drush cache:rebuild
drush deploy:hook

.env 支持

Drainpipe 将添加 .env 文件支持以管理环境变量。

这仅用于本地 - 其他环境（例如 CI 和生产）应使用其本机环境变量机制。

这包括

.env 和 .env.defaults 文件的创建
默认 Taskfile.yml 包含 dotenv 支持 注意：真实环境变量将覆盖这些
通过 vlucas/phpdotenv 集成 Drupal。要启用此功能，请将以下内容添加到您的 composer.json
```
"autoload-dev":
{
  "files": [
    "vendor/lullabot/drainpipe/scaffold/env/dotenv.php"
  ]
},
```
如果您对 .env 或 .env.defaults 进行了任何更改，您需要重新启动 DDEV。

SASS 编译

这使用 Sass 编译 CSS 资产。它还支持以下功能

通配符匹配
```
// Base
@use "sass/base/**/*";
```
现代规范化器
通过项目根目录中的 .browserslistrc 文件配置 Autoprefixer

设置

将 @lullabot/drainpipe-sass 添加到您的项目 yarn add @lullabot/drainpipe-sass 或 npm install @lullabot/drainpipe-sass

编辑 Taskfile.yml 并在 vars 部分添加 DRAINPIPE_SASS

vars:
  DRAINPIPE_SASS: |
    web/themes/custom/mytheme/style.scss:web/themes/custom/mytheme/style.css
    web/themes/custom/myothertheme/style.scss:web/themes/custom/myothertheme/style.css

运行 task sass:compile 以检查其是否按预期工作
运行 task sass:watch 以检查文件监视是否按预期工作

将任务添加到编译所有资产的任务中，例如

assets:
  desc: Builds assets such as CSS & JS
  cmds:
    - yarn install --immutable --immutable-cache --check-cache
    - task: sass:compile
    - task: javascript:compile
assets:watch:
  desc: Builds assets such as CSS & JS, and watches them for changes
  deps: [sass:watch, javascript:watch]

JavaScript 编译

JavaScript 打包支持通过 esbuild 实现。

设置

将 @lullabot/drainpipe-javascript 添加到您的项目 yarn add @lullabot/drainpipe-javascript 或 npm install @lullabot/drainpipe-javascript
编辑 Taskfile.yml 并在 vars section 添加 DRAINPIPE_JAVASCRIPT
```
DRAINPIPE_JAVASCRIPT: |
  web/themes/custom/mytheme/script.js:web/themes/custom/mytheme/script.min.js
  web/themes/custom/myotherthemee/script.js:web/themes/custom/myothertheme/script.min.js
```
由于无法提供单独的 entryNames，源和目标需要具有相同的基于目录（web 或 docroot）。请参阅 evanw/esbuild#224
运行 task javascript:compile 以检查其是否按预期工作
运行 task javascript:watch 以检查文件监视是否按预期工作

将任务添加到编译所有资产的任务中，例如

assets:
  desc: Builds assets such as CSS & JS
  cmds:
    - yarn install --immutable --immutable-cache --check-cache
    - task: sass:compile
    - task: javascript:compile
assets:watch:
  desc: Builds assets such as CSS & JS, and watches them for changes
  deps: [sass:watch, javascript:watch]

测试

这是由单独的 drainpipe-dev 包提供的（因此开发/测试依赖项不会在生产构建中安装）。

静态测试

以下所有静态代码分析测试都可以通过 task test:static 运行

修改 PHP_CodeSniffer 配置

创建 phpcs.xml 以覆盖 phpcs.xml.dist 文件，并在其中执行覆盖操作
```
<rule ref="phpcs.xml.dist">
</rule>
```

在项目根目录中编辑 phpcs.xml，例如添加排除模式

<!-- Custom excludes -->
<exclude-pattern>web/sites/sites.php</exclude-pattern>

功能测试

功能测试需要一些机制来创建一个用于测试的 functioning Drupal 网站。以下所有测试都可以通过 task test:functional 运行

PHPUnit

task test:phpunit:functional

在以下目录中运行 PHPUnit 测试

web/modules/custom/**/tests/src/Kernel
test/phpunit/**/Kernel
web/modules/custom/**/tests/src/Functional
test/phpunit/**/Functional
web/modules/custom/**/tests/src/FunctionalJavaScript
test/phpunit/**/FunctionalJavaScript

在运行这些测试之前，您需要确保您有一个可工作的 Drupal 网站。

包含对 Drupal Test Traits 的支持，在您的 Taskfile.yml 变量中设置此内容

vars:
  DRUPAL_TEST_TRAITS: true

这将另外查找以下目录中的测试

web/modules/custom/**/tests/src/ExistingSite
test/phpunit/**/ExistingSite
web/modules/custom/**/tests/src/ExistingSiteJavascript
test/phpunit/**/ExistingSiteJavascript

请注意：DTT 测试将针对主工作 Drupal 网站运行，而不是安装一个新的独立实例

Nightwatch

task test:nightwatch

使用 Nightwatch 运行功能浏览器测试。

运行 test:nightwatch:setup 以帮助您设置项目以运行 Nightwatch 测试，通过安装必要的节点包和 DDEV 配置。

如果您使用 DDEV，Drainpipe 将创建一个 .ddev/docker-compose.selenium.yaml 文件，该文件提供独立的 Firefox 和 Chrome 容器，以及一个示例测试在 test/nightwatch/example.nightwatch.js 中。

要运行上述测试，您需要在 Firefox 和 Chrome 容器中有一个可工作的 Drupal 安装。您可以运行 test:nightwatch:siteinstall 辅助任务来为两个网站运行您的现有配置的 Drupal 网站安装器。

在验证此测试正常工作后，您可以在 composer.json 中忽略它

"extra": {
        "drupal-scaffold": {
            "file-mapping": {
                "[project-root]/test/nightwatch/example.nightwatch.js": {
			"mode": "skip"
		}
	}
}

Nightwatch 测试必须具有 .nightwatch.js 后缀才能被测试运行器识别。

当测试正在运行时，您可以通过浏览器实时查看它们。

https://:7900 用于 Chrome https://:7901 用于 Firefox

所有环境的密码是 secret。

自动修复

task test:autofix 尝试自动修复测试发现的任何问题。目前，这仅通过 PHPCBF 修复 PHPCS 错误。

托管提供商集成

通用

通用部署助手可在以下位置找到：tasks/snapshot.yml, tasks/deploy.yml, 和 tasks/drupal.yml

导入/导出数据库

数据库默认下载到 /var/www/html/files/db/db.sql.gz，这可以通过 Task 中的变量覆盖

`task drupal:import-db DB_DIR="/var/www/htdocs"`

快照

创建当前工作目录文件的快照时，可以使用位于存储库根目录的 .drainpipeignore 文件排除这些文件夹，该文件格式与 .gitignore 相同，例如。

# Files that won't be deployed to Pantheon
/.ddev
/.github
/.yarn
/files/db
/tests
/.env
/.env.defaults
/README.md
/Taskfile.yml
*.sql
*.sql.gz

然后可以将此文件夹作为存档部署到远程服务，或使用 task deploy:git 推送到 git 远程。

Pantheon

Pantheon 特定任务包含在 tasks/pantheon.yml 中。要将它们添加到您的 Taskfile.yml 的 includes 部分，请添加以下内容

includes:
  pantheon: ./vendor/lullabot/drainpipe/tasks/pantheon.yml

有关托管提供商的 CI 特定集成，请参见以下内容。

当使用 Drainpipe 与 Pantheon 时，Pantheon 网站应配置为覆盖 Pantheon 的一些默认行为。由于 Drainpipe 安装 composer 依赖项，应禁用 Pantheon 的 Integrated Composer。将 build_step: false 添加到您的 pantheon.yml 文件

---
api_version: 1
build_step: false

此外，Pantheon 网站以 "Autopilot" 开头，它提供了来自 Drupal 上游的更新。通常此功能与 GitHub 或 GitLab 等外部 Git 存储库冲突。建议使用 terminus 设置为空的上游来禁用此功能。

ddev ssh
terminus site:upstream:set [site_name] empty

GitHub Actions 集成

将以下内容添加到 composer.json 中，以便将通用的 GitHub Actions 复制到项目中的 .github/actions/drainpipe

"extra": {
  "drainpipe": {
    "github": []
  }
}

它们是组合操作，可以在任何工作流程中使用，例如。

- uses: ./.github/actions/drainpipe/set-env

- name: Install and Start DDEV
  uses: ./.github/actions/drainpipe/ddev
  with:
    git-name: Drainpipe Bot
    git-email: no-reply@example.com
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
    ssh-known-hosts: ${{ secrets.SSH_KNOWN_HOSTS }}

可以使用 act 在本地运行测试：act -P ubuntu-latest=ghcr.io/catthehacker/ubuntu:runner-latest -j Static-Tests

测试

可以使用以下配置添加运行静态和功能测试的工作流程

"extra": {
  "drainpipe": {
    "github": ["TestStatic", "TestFunctional"]
  }
}

功能测试的构建过程将使用 task build:ci:functional，如果失败则回退到 task build:dev，然后 task build。静态测试不应需要构建步骤。

这些工作流程文件将由 Drainpipe 继续管理，无法覆盖。如果您想这样做，则建议您维护自己的测试工作流程。

安全

"extra": {
  "drainpipe": {
    "github": ["Security"]
  }
}

对 composer 包和 Drupal contrib 运行安全检查，并作为审阅评论发布 composer.lock 的差异。

Composer Lock 差异（已弃用）

现在，它作为安全工作流程的一部分提供

使用 composer-lock-diff，将 composer.lock 中检测到的任何更改更新为拉取请求描述中的 markdown 表格。

"extra": {
    "drainpipe": {
        "github": ["ComposerLockDiff"]
    }
}

Pantheon

要启用 Pantheon Review Apps 的部署

添加以下 composer.json

"extra": {
    "drainpipe": {
        "github": ["PantheonReviewApps"]
    }
}

运行 composer install 将工作流程安装到 .github/workflows
将以下变量添加到您的 GitHub 存储库
- PANTHEON_SITE_NAME Pantheon 中的规范网站名称
- TERMINUS_PLUGINS（可选）逗号分隔的可用 Terminus 插件列表
将以下 secrets 添加到您的 GitHub 仓库
- PANTHEON_TERMINUS_TOKEN 请参阅 https://pantheon.io/docs/terminus/install#machine-token
- SSH_PRIVATE_KEY 用户私钥，可用于向 Pantheon 推送
- SSH_KNOWN_HOSTS 运行 ssh-keyscan -H -p 2222 codeserver.dev.$PANTHEON_SITE_ID.drush.in 的结果
- PANTHEON_REVIEW_USERNAME （可选）HTTP 基本认证的本地用户名
- PANTHEON_REVIEW_PASSWORD （可选）用于锁定站点的密码

GitLab CI 集成

为 GitLab 辅助工具将以下内容添加到 composer.json

"extra": {
  "drainpipe": {
    "gitlab": []
  }
}

这将导入 scaffold/gitlab/Common.gitlab-ci.yml，它提供了可用于 GitLab CI 的辅助工具，可以使用 includes 和 references，或如果使用 DDEV，则使用 scaffold/gitlab/DDEV.gitlab-ci.yml

include:
  - local: '.gitlab/drainpipe/DDEV.gitlab-ci.ymll'

variables:
  DRAINPIPE_DDEV_GIT_EMAIL: drainpipe-bot@example.com
  DRAINPIPE_DDEV_GIT_NAME: Drainpipe Bot

build:
  stage: build
  interruptible: true
  script:
    - !reference [.drainpipe_setup_ddev, script]
    - composer install
    - ddev restart
    - ddev drush site:install minimal -y
    - echo "\$settings['config_sync_directory'] = '../config';" >> web/sites/default/settings.php
    - ddev drush config:export -y
    - ddev task update

可用的变量有

Composer 锁定差异

使用 composer-lock-diff 更新合并请求描述，其中包含使用 composer.lock 中检测到的任何更改的 markdown 表格。需要设置 GITLAB_ACCESS_TOKEN 变量，它是一个具有 api 范围的访问令牌。

"extra": {
    "drainpipe": {
        "gitlab": ["ComposerLockDiff"]
    }
}

Pantheon

"extra": {
    "drainpipe": {
        "gitlab": ["Pantheon", "Pantheon Review Apps"]
    }
}

将以下内容添加到 composer.json 中以启用 Pantheon Review Apps 的部署

"extra": {
    "drainpipe": {
        "github": ["PantheonReviewApps"]
    }
}

运行 composer install
将您的 Pantheon site-name 添加到新工作流程文件 .github/workflows/PantheonReviewApps.yml 的最后一个作业中
将以下变量添加到您的 GitLab 仓库
- PANTHEON_TERMINUS_TOKEN 请参阅 https://pantheon.io/docs/terminus/install#machine-token （启用 Mask variable 复选框）
- SSH_PRIVATE_KEY 用户私钥，可用于向 Pantheon 推送（启用 Mask variable 复选框）
- SSH_KNOWN_HOSTS 运行 ssh-keyscan -H -p 2222 codeserver.dev.$PANTHEON_SITE_ID.drush.in 的结果（启用 Mask variable 复选框）
- TERMINUS_PLUGINS 可用 Terminus 插件的逗号分隔列表（可选）

这将设置合并请求部署到 Pantheon Multidev 环境。请参阅 [scaffold/gitlab/gitlab-ci.example.yml] 以获取示例。您还可以仅包含它，这将为您提供可以包含和引用的任务的辅助工具，例如设置 Terminus。请参阅 scaffold/gitlab/Pantheon.gitlab-ci.yml。

Tugboat

将以下内容添加到 composer.json 以添加 Tugboat 配置

{
    "extra": {
        "drainpipe": {
            "tugboat": {}
        }
    }
}

以下内容将根据您的 .ddev/config.yml 自动检测

Web 服务器（nginx 或 apache）
PHP 版本
数据库类型和版本
nodejs 版本
Redis（使用 ddev get ddev/ddev-redis 获取）

此外，还可以添加 Pantheon Terminus

{
    "extra": {
        "drainpipe": {
            "tugboat": {
              "terminus": true
            }
        }
    }
}

假设以下任务存在

sync
build
update

如果需要，可以使用 sync:tugboat、build:tugboat 和 update:tugboat 任务覆盖 build、sync 和 update 任务（如果您第一次将此任务添加到您的 Taskfile.yml，则需要重新运行 composer install 以重新生成 Tugboat 脚本）。

  sync:
    desc: "Fetches a database from Pantheon and imports it"
    cmds:
      - task: pantheon:fetch-db
      - task: drupal:import-db
  sync:tugboat:
    desc: "Fetches a database from Pantheon and imports it in Tugboat"
    cmds:
      - task: pantheon:fetch-db
        vars:
          DB_DIR: /var/lib/tugboat/files/db
      - task: drupal:import-db
        vars:
          DB_DIR: /var/lib/tugboat/files/db

💡 如果对 DDEV 配置进行了任何更改，则应重新运行 composer install

您可以通过将它们添加到您的 Taskfile.yml 中来挂钩到镜像的 init 步骤，例如：

tugboat:php:init:
  cmds:
    - apt-get install -y libldap2-dev
    - docker-php-ext-install ldap

您还可以通过添加名为 online:tugboat 的任务并重新运行 composer install 来添加一个 online 步骤。

排水管将完全管理你的.tugboat/config.yml文件，请不要编辑它。以下键可以通过.tugboat/config.drainppipe-override.yml文件添加到你的config.yml

php:
  aliases:
  urls:
  screenshot:
  visualdiff:

贡献者文档

此仓库是公开的。

请小心删除发布问题时或评论中的敏感客户信息。

首次贡献者需要维护者批准才能运行自动化测试。（这是为了避免意外或恶意地产生大型的CI账单。）

通过查看PR代码更改进行同行评审是很好的。

在实际网站上测试PR代码更改是非常有益的。

本地开发

要测试本地更改，请遵循测试脚本的说明。

自动化更新的同行评审指南

这是关于对Renovate创建的自动化依赖关系更新拉取请求进行同行评审的指南。

所有由Renovate提交的自动化更新都通过GitHub Actions进行一系列的自动化测试。这些测试旨在确保与依赖项新版本的兼容性和稳定性。

所有Renovate同行评审，无论是否是次要或补丁发布，都需要

仔细阅读变更日志，以了解新功能和修复内容。
- 评估是否需要额外的测试覆盖率，或者这些更改可能影响现有功能。
- 考虑新功能对项目未来开发和维护的影响。
所有测试和检查必须通过

处理版本范围

一些依赖项允许多个版本，例如"drush/drush": "^10|^11|^12"。

当这些版本中的任何一个发布补丁或次要版本时，Renovate将创建拉取请求。
我们不想合并这些，因为这会将这些包固定到特定版本。
我们想允许这些拉取请求运行检查。这将确认Drainpipe支持的范围内最新版本不太可能破坏构建。
所有GitHub Action检查通过后，在拉取请求上留下这样的评论，关闭拉取请求，并删除分支。

处理测试失败

有时，测试可能由于瞬态问题或测试套件的不可靠性而失败。在这种情况下

验证测试失败的性质，以确保它不是与依赖关系更新相关的。
如果失败似乎与更新无关，请重新运行GitHub Actions作业以确认问题是否持续。
在拉取请求上记录任何反复出现的不可靠性或问题，然后创建一个新的与拉取请求链接的问题，以便进一步调查。

进行同行评审

审查自动化更新拉取请求（PR）:
- 确保PR标题和描述清楚地描述了更新及其范围。
- 检查更改的文件列表，以了解更新的范围。
评估测试结果:
- 确保所有GitHub Actions测试都通过。请特别注意涉及更新依赖项的测试。
- 对于失败的测试，请遵循上面的“处理测试失败”指南。
阅读依赖项变更日志:
- 对于次要版本，请审查依赖项的变更日志，以确定任何重大更改或新增内容。
- 评估这些更改可能如何影响Drainpipe项目。
最终决定:
- 对于所有测试都通过的小修补版本，继续合并更新。
- 对于次要版本，在彻底审查和考虑后，决定是否合并更新或请求在合并前手动测试。

发布

drainpipe和drainpipe-dev发布流程

发布时，根据https://semver.org/增加版本。

MAJOR版本当您进行不兼容的API更改时 MINOR版本当您以向后兼容的方式添加功能时 PATCH版本当您进行向后兼容的错误修复时

特别针对排水管，当添加新的“检查”时，可能会破坏项目中的构建，这通常是一个小版本更新，包含关于变更的发布说明。

在制作新版本发布之前，请在 lullabot 内部 #devops slack 频道发布信息，与其他维护者进行协调。

为 drainpipe 生成 GitHub 发布版本。
根据变更和语义版本标准提供正确的标签。
使用“生成发布说明”按钮，并审查变更以确认新版本根据语义版本标准是正确的。
将该版本设置为最新并发布。
发布后将自动启动使用 drainpipe-dev 的发布，该发布基于 DrainpipeDev GitHub 工作流程。
访问项目板并存档“准备发布”列。

NPM 包发布流程

要生成新的 NPM 包发布

确保本地检出最新的主分支
运行 yarn install && yarn lerna publish

lullabot / drainpipe

维护者

详细信息

README

安装

二进制文件

数据库更新

.env 支持

SASS 编译

设置

JavaScript 编译

设置

测试

静态测试

修改 PHP_CodeSniffer 配置

功能测试

PHPUnit

Nightwatch

自动修复

托管提供商集成

通用

导入/导出数据库

快照

Pantheon

GitHub Actions 集成

测试

安全

Composer Lock 差异（已弃用）

Pantheon

GitLab CI 集成

Composer 锁定差异

Pantheon

Tugboat

贡献者文档

本地开发

自动化更新的同行评审指南

处理版本范围

处理测试失败

进行同行评审

发布

drainpipe和drainpipe-dev发布流程

NPM 包发布流程