wp-github-actions

WordPress Plugin GitHub Actions

此技能可帮助你使用 GitHub Actions 为 WordPress 插件设置全面的 CI/CD 流水线，旨在帮助插件作者减少人工工作量，同时交付更高质量的代码。

此技能涵盖的内容

一个完善的 WordPress 插件应当具备多类工作流。并非每个插件都需要全部工作流——合适的组合取决于插件的复杂程度、是否包含 JavaScript/CSS 资源、是否使用 Composer 等。你的任务是判断哪些工作流适用，并进行设置。

工作流分为以下几类：

1. 代码质量 — WPCS/PHPCS 检查、PHP lint、JS/CSS lint
2. 测试 — 使用 WordPress 测试库进行 PHPUnit 测试
3. 静态分析 — 使用 WordPress 扩展的 PHPStan
4. 依赖管理 — PR 上的 Composer 差异检查、安全扫描
5. 预览 — WordPress Playground PR 预览
6. 部署 — 在标记/发布时自动部署到 WordPress.org

阅读 references/workflows.md，了解各工作流的详细配置，包括可直接使用的 YAML 模板和配置文件。

如何处理请求

第 1 步：了解插件

编写任何工作流文件之前，先了解你要处理的项目：

• 插件是否使用 Composer？ 检查是否有 composer.json。如果有，则 Composer 相关工作流（差异检查、安全扫描、自动加载）适用。
• 是否包含 JavaScript/CSS 资源？ 检查是否有 package.json、JS/CSS 源文件或构建流程。如果有，则 JS/CSS lint 和可能的构建步骤很重要。
• 是否有测试？ 检查是否有 tests/ 目录、phpunit.xml 或 phpunit.xml.dist。如果有，则设置 PHPUnit 工作流。如果没有，请说明添加测试会很有价值，但不要强行要求。
• 是否发布在 WordPress.org 上？ 检查是否有 .wordpress-org 目录，或向用户询问。如果有，则部署工作流适用，你还应该设置 .distignore。
• 应支持哪些 PHP 版本？ WordPress 本身要求 PHP 7.4 及以上版本，但许多插件以 7.4、8.0、8.1、8.2 和 8.3 为目标版本。检查插件的 readme，或向用户询问。
• 支持哪些 WordPress 版本？ 同样，检查插件声明兼容的 WP 版本。

第 2 步：推荐一组工作流

根据你的调查结果，推荐要设置的工作流。大多数插件适用的默认方案：

• WPCS 检查（几乎总是适用）
• PHP lint（几乎总是适用——可检查不同 PHP 版本中的语法错误）
• PHPUnit 测试（如果存在测试）
• 部署到 WordPress.org（如果发布在 WordPress.org 上）
• Playground PR 预览（所有插件都值得考虑）

有条件适用的工作流：

• JS/CSS lint（如果插件包含前端资源）
• Composer 差异检查 + 安全扫描（如果使用 Composer）
• PHPStan（适用于需要更深入静态分析的插件）

第 3 步：创建工作流文件

将每个工作流创建为 .github/workflows/ 中的独立 YAML 文件。与单体工作流相比，使用独立文件能在 PR 中提供更清晰的反馈（每项检查都会单独显示），也更便于启用或禁用各项检查。

以 references/workflows.md 中的模板为起点，并根据具体插件进行调整。常见的调整包括修改 PHP 版本矩阵、更改 WPCS 标准、调整文件路径，以及为包含构建步骤的插件调整部署工作流。

第 4 步：创建辅助配置文件

根据设置的工作流，你可能还需要：

• phpcs.xml.dist — 自定义 PHPCS 规则集（如果插件需要排除规则或使用自定义配置）
• .distignore — 从 WordPress.org 部署中排除的文件
• phpstan.neon 或 phpstan.neon.dist — PHPStan 配置

第 5 步：设置密钥提醒

如果你添加了部署工作流，请提醒用户需要在 GitHub 中配置两个仓库密钥：

• SVN_USERNAME — 他们的 WordPress.org 用户名
• SVN_PASSWORD — 他们的 WordPress.org 密码

引导他们前往：仓库设置 > 密钥和变量 > Actions > 新建仓库密钥。

命名约定

使用描述性工作流文件名，让人一眼就能看出每个文件的用途：

• wpcs.yml — WordPress 编码标准
• phpunit.yml — PHPUnit 测试
• lint-php.yml — PHP 语法检查
• lint-js-css.yml — JavaScript 和 CSS 检查
• phpstan.yml — 静态分析
• composer-diff.yml — PR 中的 Composer 依赖差异
• security.yml — Composer 安全扫描
• playground-preview.yml — WordPress Playground PR 预览
• deploy.yml — 部署到 WordPress.org

重要细节

分支命名：许多 WordPress 插件仓库使用 trunk 作为默认分支（与 WordPress.org SVN 约定保持一致），而其他仓库则使用 main 或 master。务必检查实际仓库，并在工作流触发器中使用正确的分支名称。

PHP 版本矩阵：WordPress 6.x 要求 PHP 7.4 或更高版本。PHPUnit 的一个良好默认矩阵是 ['7.4', '8.0', '8.1', '8.2', '8.3']，但 WPCS 和代码检查只需使用最新稳定版 PHP（无需矩阵）。

WordPress 版本矩阵：对于 PHPUnit，至少要针对 latest 进行测试，并考虑添加前一个主版本。一些插件还会针对 nightly 进行测试，以便及早发现潜在问题。

10up 生态系统：10up 维护了一组专为 WordPress 打造且维护良好的 GitHub Actions。优先使用这些操作，而不是通用替代方案（如果有的话）——它们能很好地处理 WordPress 特有的边缘情况。主要操作包括用于编码标准的 10up/wpcs-action 和用于部署的 10up/action-wordpress-plugin-deploy。