Gutenberg 的 Core Backport Changelog 机制如何将插件改动回传 WordPress Core 并纳入自动化校验【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg本篇文章围绕 Gutenberg 插件仓库中的 backport-changelog/readme.md 展开系统讲解Core Backport Changelog核心回传变更日志这一仓库级协作机制的完整运作方式哪些文件改动会被判定为需要回传 WordPress Core、如何创建对应的 Core PR、如何在仓库中登记回传条目、CI 如何自动校验、以及存在哪些豁免规则。读完本文你将掌握为 Gutenberg PR 正确登记 Core 回传条目的完整流程理解backport-changelog目录的设计动机与配套自动化并能快速定位仓库中的真实条目作为参考。一、背景为什么 Gutenberg 需要回传到 WordPress CoreGutenberg 是 WordPress 的块编辑器项目插件本身从官方仓库发布。但 Gutenberg 中的大量 PHP 能力例如lib/下的区块支持逻辑、PHP 单元测试等在 WordPress 大版本发布时会被合并back-merge进 WordPress Core成为下一次 WordPress 正式版本的一部分。这意味着任何改动或新增了 Gutenberg 插件文件尤其涉及 PHP 文件与 PHP 单元测试的 PR都需要确认这些改动是否应当回传到 WordPress Core。在打开 Gutenberg PR 时对某些文件的改动会被自动标记为需要回传 Core例如 lib/ 目录下的 PHP 文件和phpunit/下的 PHP 单元测试。核心规则是被标记为需要回传的改动必须存在一个对应的 Core PR之后才能合并到 Gutenberg 的trunk分支。换句话说先有 Core PR后有 Gutenberg 合并是这类改动的硬性前置条件。二、哪些文件改动会触发需要 Core 回传的判定判定并非人工主观进行而是由仓库中的 GitHub Actions 工作流在 PR 打开时自动完成。对应实现见 .github/workflows/check-backport-changelog.yml其pull_request触发条件的paths字段精确列出了需要校验的路径范围。需要回传的路径触发校验lib/**—— 插件核心 PHP 逻辑目录phpunit/**—— PHP 单元测试目录packages/**/*.php—— 各包中的 PHP 文件但有大量排除项见下。默认排除的路径不触发校验工作流中通过!前缀的路径模式排除掉无需回传的文件例如!lib/load.php—— 插件专属代码!lib/experiments-page.php—— 实验功能页属插件专属!lib/theme.json!lib/experimental/**—— 实验性目录!phpunit/experimental/**、!phpunit/blocks/**!packages/block-library/**、!packages/block-serialization-default-parser/**、!packages/widgets/**、!packages/e2e-tests/**、!packages/icons/src/manifest.php。这一白名单 黑名单的路径设计与仓库协作文档 docs/contributors/code/back-merging-to-wp-core.md 中列出的回传标准保持一致lib/与phpunit/是核心回传来源而lib/load.php、lib/experiments-page.php、packages/block-library、packages/e2e-tests/plugins、phpunit/blocks等属于插件专属或自动同步范围无需人工回传。三、创建 Core PR回传流程的第一步当你的 Gutenberg PR 被判定需要回传时需要先创建一个对应的 Core PR流程如下先在 WordPress Core 的 Trac 上新建一个 Trac ticketCore 侧的工单编号体系向 WordPress Core 的 GitHub 仓库WordPress/wordpress-develop提交一个 pull request并在其中关联上述 Trac ticket这个 Core PR 可以保持打开状态所需时间多长都可以——它不阻塞流程但必须存在。关于 Core PR 的具体写法Gutenberg 路径到 WP Core 路径的映射规则等可以参考仓库内的协作文档 docs/contributors/code/back-merging-to-wp-core.md例如lib/block-supports/layout.php对应src/wp-includes/block-supports/layout.php这类直接同步文件以及lib/compat/wordpress-X.Y/兼容层文件的移植方式。四、登记回传条目在 backport-changelog 中添加 markdown 文件创建完 Core PR 后还需要在 Gutenberg 仓库中登记一条回传记录让 CI 能够验证这个 Gutenberg PR 有对应的 Core PR。4.1 目录结构按 WordPress 版本分子目录backport-changelog/目录下按 WordPress 发布版本分子目录存放条目例如当前仓库中包含6.6、6.7、6.8、6.9、7.0、7.1、7.2等版本目录见 backport-changelog/6.9 等目录。每个版本目录对应该改动将被纳入的 WordPress 大版本。4.2 文件命名以 Core PR 编号命名条目的文件名就是 Core PR 的编号。例如如果你的 Core PR 编号是1234且该改动计划进入 WordPress 6.9 版本那么文件名应为1234.md并放置在 backport-changelog/6.9 目录下。如果对应版本目录尚不存在需要自行创建该目录。4.3 文件内容Core PR URL Gutenberg PR URL 列表markdown 文件的内容格式为第一行是 Core PR 的 GitHub URL其后列出被该 Core PR 回传的 Gutenberg PR 的 GitHub URL 列表。沿用文档中的示例假设下一个 WordPress 版本是 6.9你有两个 Gutenberg PR编号1111与2222它们的改动由同一个 Core PR编号1234一次性回传则应在backport-changelog/6.9/下创建1234.md内容如下https://github.com/WordPress/wordpress-develop/pull/1234 * https://github.com/WordPress/gutenberg/pull/1111 * https://github.com/WordPress/gutenberg/pull/2222几点要点如果1234.md已经存在说明该 Core PR 之前已登记过其他 Gutenberg PR只需把新的 Gutenberg PR URL 追加到现有文件中的列表里即可不要新建文件一个 Core PR 可以同时承载一个或多个Gutenberg PR 的改动回传列表项以*开头这一格式同时被 CI 校验脚本与后续的自动同步脚本所依赖详见下文。4.4 仓库中的真实条目示例仓库中已有大量真实条目可供对照学习backport-changelog/6.9/5486.mdCore PR5486回传了 Gutenberg PR71594backport-changelog/6.9/9992.mdCore PR9992回传了 Gutenberg PR71820backport-changelog/7.1/6910.md单个 Core PR6910同时回传了59483、60652、62777、63108、63464共五个 Gutenberg PR——这正是一个 Core PR 对应多个 Gutenberg PR的典型实例。五、CI 自动校验check-backport-changelog 工作流登记完成后CI 会验证回传条目是否满足要求。核心逻辑在 .github/workflows/check-backport-changelog.yml 中5.1 触发时机事件pull_request类型为opened、synchronize、labeled、unlabeled分支仅针对trunk分支的 PR路径匹配上文列出的需要回传的路径范围lib/**、phpunit/**、packages/**/*.php及各自的排除项。5.2 校验逻辑校验步骤用 shell 脚本完成大致流程为以当前 PR 的编号构造 Gutenberg PR 的 URL 正则https://github.com/WordPress/gutenberg/pull/${PR_NUMBER}在backport-changelog目录中递归grep查找包含该 Gutenberg PR 链接的条目文件如果找不到任何条目文件CI 失败并提示开发者请在backport-changelog目录下创建wp-release-number/core-pr-number.md文件写入 Core PR URL 和包含本 PR URL 的列表项如果改动与某个已存在的、仍打开的 Core PR 相关也可以把本 PR URL 追加到该 Core PR 的条目文件中详见 backport-changelog/readme.md如果找到了条目文件则校验其文件名去.md后缀后即为 Core PR 编号与文件内第一行的 Core PR URL 是否一致——文件名必须与 Core PR 编号匹配否则同样会 CI 失败。可以看出CI 对文件名 Core PR 编号文件首行 该编号对应的 Core PR URL文件中包含本 Gutenberg PR 的列表项这三者做了完整闭环校验。5.3 两个豁免标签CI 的 job 级条件同时检查了 PR 标签只要 PR 带有No Core Sync Required或Backport from WordPress Core标签整个校验就会被跳过。这两个标签的含义详见原文档 backport-changelog/readme.mdBackport from WordPress Core表示该 PR 本身就是从 WordPress Core 回传到 Gutenberg 的改动已在 Core 中无需再创建 Core PRNo Core Sync Required表示改动不需要同步到 WordPress Core。5.4 路径级豁免Exceptions除了标签还存在路径级的永久豁免如果某些文件或目录的改动永远不该被标记为需要 Core 回传 PR可以直接把它们加入 .github/workflows/check-backport-changelog.yml 的路径排除列表中即上文提到的!前缀项如!lib/load.php等。这类豁免适用于改动不涉及需要回传的内容的常规情况例如仅包含轻微注释修改或者改动在 Core 中已经存在。六、为什么用单个文件而非单个大 changelog原文档明确给出了设计决策的理由见 backport-changelog/readme.md 的 Why use individual files? 一节对于回传变更日志Gutenberg 使用每个条目一个独立文件而不是一个单一的 changelog 文件目的是避免 rebase 冲突。在 trunk 分支这种高并发协作场景下如果所有开发者都往同一个 changelog 文件追加内容任何一次合并都可能产生冲突而一个 Core PR 对应一个 md 文件、按版本分目录的布局让不同 PR 的登记互不干扰几乎不存在写入竞争。七、从 changelog 到 Issue 的自动同步回传条目除了供 CI 校验还会被自动汇总到 Gutenberg 仓库中带 Sync Backport Changelog标签的跟踪 Issue 上。对应实现见 .github/workflows/sync-backport-changelog.yml触发方式推送trunk分支此时会对比最近两次提交若backport-changelog目录无变化则跳过或当 Issue 被标记 Sync Backport Changelog标签时汇总逻辑找到标题中包含版本号形如\d\.\d的最新打开 Issue然后用awk处理对应版本目录下所有条目文件backport-changelog/${version}/*.md把内容合并为列表格式写入 Issue 描述中两个标记注释!-- START TRUNK BACKPORT CHANGELOG --与!-- END TRUNK BACKPORT CHANGELOG --之间的区域若已存在则整体替换否则追加到末尾。这一机制保证了回传清单始终以单一、可引用的形式沉淀在一个固定 Issue 中便于团队追踪每个 WordPress 版本的待回传内容。八、拿不准时向谁求助原文档给出的求助渠道详见 backport-changelog/readme.md如果不确定某个 PR 是否需要 Core 回传 PR可以在 Gutenberg PR 上WordPress/gutenberg-core团队或通过 WordPress Slack 的#core-editor频道提问。此外也可以对照仓库内的 docs/contributors/code/back-merging-to-wp-core.md 了解更完整的回传标准与文件映射细节。小结一次完整的回传登记流程将上述内容串起来一个 Gutenberg 改动被正确回传并登记的标准流程是提交 Gutenberg PR改动涉及lib/**、phpunit/**等需要回传的路径在 Core 侧创建 Trac ticket并向wordpress-develop提交 Core PR在 Gutenberg 仓库的backport-changelog/版本/目录下以 Core PR 编号为文件名创建.md条目或追加到已存在的同名文件中第一行写 Core PR URL其后列出本 Gutenberg PR 的 URL若改动确实无需回传为 PR 打上No Core Sync Required或Backport from WordPress Core标签以跳过校验CIcheck-backport-changelog自动校验通过后PR 才能合并到trunk合并后sync-backport-changelog工作流将条目自动同步到跟踪 Issue供后续 WordPress 版本发布时核对。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考