Gutenberg 仓库遵循 WordPress SVN 仓库针对每个主要 WordPress 版本的分支策略。此外，它还包含另外两个特殊分支，用于控制 npm 发布工作流：

  • wp/latest 分支包含与带有 latest 分发标签发布到 npm 的软件包版本相同的软件包。这里的目标是让该分支与最后一次 Gutenberg 插件发布保持同步，唯一的例外是计划外的错误修复发布。
  • wp/next 分支包含与带有 next 分发标签发布到 npm 的软件包版本相同的软件包。它始终与 trunk 分支保持同步。项目应仅将这些软件包用于开发或测试目的。
  • 针对特定 WordPress 主版本（包括其后续的小版本增量）的 Gutenberg 分支 wp/X.Y（例如 wp/6.2），会在计划纳入下一个 WordPress 主版本的最后一次发布后不久，基于当前的 Gutenberg 插件发布分支 release/X.Y（例如 release/15.1）创建。

发布类型及其时间表：

  • 同步 Gutenberg 插件（latest dist tag）– 每两周自动进行一次发布，基于新创建的 release/X.Y 分支（例如 release/12.8），其中包含 Gutenberg 插件的 RC1 版本。
  • WordPress 发布（wp-X.Y dist tag，例如 wp-6.2）– 从 wp/X.Y 分支（例如 wp/6.2）按需触发发布。一旦我们到达 WordPress 主版本发布周期中的某个时间点（Beta 1 之前不久），此时我们仅将提交从 Gutenberg 仓库挑选（cherry-pick）到 WordPress 核心中，我们会使用 wp/X.Y 分支（由 release/X.Y 分支创建，例如 release/15.1）进行带有 wp-X.Y dist-tag 的 npm 发布。也可以使用较旧的分支将错误或安全修复回迁（backport）到相应旧版本的 WordPress Core。
  • 开发版发布（next dist tag）– 当需要测试即将推出的更改时，也可以随时执行开发版发布。

还有一个选项可以随意执行独立错误修复软件包发布。这应该仅保留给必须在常规周期之外发布到 npm 的关键错误修复或安全发布。

同步 Gutenberg 插件

对于每次 Gutenberg 插件发布，我们还会向 npm 发布更新版本的 WordPress 软件包。这是通过处理 Gutenberg 插件发布的 Release Tool 自动完成的。成功的 RC1 发布会触发 npm 发布任务，这需要由 Gutenberg Core 团队成员批准。找到新版本的 “Build Gutenberg Plugin Zip” workflow，并使其获得批准。

我们在 Gutenberg 仓库内故意在 Gutenberg RC1 发布时，用来自 Gutenberg 发布 release/X.Y 分支（例如 release/12.7）的内容更新 wp/latest 分支。这样做是为了确保 wp/latest 分支尽可能接近最新版本的 Gutenberg 插件。这也实际上消除了在向 trunk 回迁提交时的冲突可能性，这些提交包含在发布到 package.json 和 CHANGELOG.md 文件期间应用的更新。过去，在一周后的常规 Gutenberg 发布之后进行 npm 发布时，在这方面存在许多问题。在将新的软件包版本发布到 npm 时，我们至少选择 minor 版本号提升，以考虑到未来的错误修复或安全发布。

在幕后，所有步骤都通过 npm exec --no release-cli -- npm-latest 自动化。记录显示，手动过程看起来非常接近以下步骤：

  1. 确保 WordPress trunk 分支开放供增强功能使用。
  2. 使用 git fetch 获取最后发布的 Gutenberg 发布分支。
  3. 检出 wp/latest 分支。
  4. 删除当前分支中的所有文件：git rm -r .。
  5. 从发布分支检出所有文件：git checkout release/x.x -- .。
  6. 使用 git commit -m "Merge changes published in the Gutenberg plugin vX.X release" 将所有更改提交到 wp/latest 分支并推送到仓库。
  7. 使用计算出的新发布版本更新软件包的 CHANGELOG.md 文件并提交到 wp/latest 分支。假设软件包版本使用此格式编写 major.minor.patch，请确保应用至少 minor 版本号提升。例如，如果要发布的软件包的 CHANGELOG 指示下一个未发布版本是 5.6.1，则在 minor 版本情况下选择 5.7.0 作为版本。这一点很重要，因为补丁版本号应保留以防需要为次要 WordPress 版本进行错误修复（见下文）。
  8. 通过控制台登录 npm：npm login。请注意，您应该启用 2FA。
  9. 从 wp/latest 分支，使用 npm ci 安装 npm 依赖项。
  10. 运行脚本 npm exec --no -- lerna publish --no-private。
    • 当被要求为每个软件包选择版本号时，选取更新的 CHANGELOG 文件的值。
    • 您会被要求输入一次性密码 (OTP) 几次。这是您使用的 2FA 身份验证器应用程序中的代码。根据要发布的软件包数量，可能会被要求多次输入 OTP，因为它们往往在所有软件包发布之前过期。
    • 如果发布过程最终未完成（可能是因为超时或引入了错误的 OTP），请在恢复之前检查 npm 状态，使用 npm exec --no -- lerna publish from-package。参见从不完整的 npm 发布中恢复。
  11. 最后，既然 npm 软件包已发布，请将 lerna 创建的提交（“Publish” 和 CHANGELOG 更新）挑选（cherry-pick）到 Gutenberg 的 trunk 分支中。

从不完整的 npm 发布中恢复

如果 npm 发布中途失败，不要假定每个目标软件包版本仍未发布。某些预期版本可能已经存在于 npm 上，而发布分支、软件包标签或 dist-tags 仍需要恢复。

在重启任何修改性步骤之前，请检查失败作业中列出的软件包的 npm 注册表状态。不要从作业停止的软件包推断剩余的工作；重试或手动恢复尝试可能会留下非连续的一组已发布软件包版本。

首先，使用相同的发布类型重新运行失败的 workflow。在它准备另一个发布之前，release tool 会查找失败运行保存的提交和软件包标签。如果找到它们，它会检出该确切提交并从最后验证的状态恢复发布、Git 元数据或最终化。

准备好的状态存储在目标发布分支的命名空间下：

  • latest 和 bugfix：refs/npm-release/wp-latest/*
  • next：refs/npm-release/wp-next/*
  • WordPress X.Y：refs/npm-release/wp-X.Y/*

检查所有准备好的发布，或一个目标，而不改变它们：

git ls-remote --refs origin 'refs/npm-release/*'
git ls-remote --refs origin 'refs/npm-release/wp-latest/*'

不要删除准备好的状态以绕过未知或不完整的发布。先重新运行匹配的发布类型。如果注册表、发布分支和软件包标签检查证明准备好的发布已完成或不再需要，则单独删除 git ls-remote 返回的每个确切 ref：

git push origin --delete '<exact-ref-from-git-ls-remote>'

对于一个软件包：

git rev-parse HEAD
npm view @wordpress/components@X.Y.Z version gitHead --json
npm dist-tag ls @wordpress/components

要从当前发布分支检查所有软件包版本：

git rev-parse HEAD
npm exec --no -- lerna list --json --no-private | jq -r '.[] | "\(.name)@\(.version)"' | while read package_version; do
    package="${package_version%@*}"
    version="${package_version##*@}"
    echo "$package@$version"
    npm view "$package@$version" version gitHead --json || true
    npm dist-tag ls "$package"
done

仅当每个目标包在 npm 上已报告预期版本、其注册表中的 gitHead 与 git rev-parse HEAD 打印出的预发布提交相匹配，且预期的 dist-tag 指向该提交时，才手动恢复。如果工作流没有可恢复的预备状态，请继续使用 npm exec --no -- lerna publish from-package（该命令会发布尚未上传到 npm 的本地包版本，并跳过已经发布的版本），或者使用工作流生成的恢复命令（如果有打印的话）。

当工作流运行在 npm 发布成功但 Git 元数据发布失败后打印出分支或包标签恢复命令时，优先使用这些针对特定运行的命令，而不是开始新的发布流程。

WordPress 发布

当需要将错误修复或安全补丁向后移植到 WordPress Core 时，需要遵循以下工作流。这通常发生在以下几种情况：

  • 在 WordPress 发布周期的 beta 和 RC 阶段，此时用于发布的 wp/X.Y（例如 wp/5.7）分支已经存在。
  • 对于 WordPress 次要版本发布和 WordPress 安全版本发布（例如 5.1.1）。
  1. 检出相关的 WordPress 主要分支（如果次要版本是 5.2.1，则检出 wp/5.2）。
  2. 从该分支创建一个功能分支，并将所需错误修复的合并提交挑选（cherry-pick）到该分支上。可以使用 npm run other:cherry-pick 脚本来自动化挑选过程。
  3. 从此分支创建一个 Pull Request，目标为上述使用的 WordPress 主要分支。
  4. 使用“Rebase and Merge”按钮合并 Pull Request，以保持提交历史。

现在，wp/X.Y 分支已准备好发布 npm 包。要启动此过程，请前往 Gutenberg GitHub 仓库的 Actions 选项卡，找到 “Publish npm packages” action。注意显示“This workflow has a workflow_dispatch event trigger.”的蓝色横幅，并展开其右侧的“Run workflow”下拉菜单。

npm 发布的 Run workflow 下拉菜单

要为 WordPress 主要版本发布 npm 包，请选择 trunk 作为运行工作流的分支（这意味着用于运行工作流的脚本来自 trunk 分支，但只要下面选择了正确的“Release type”，包本身将从发布分支进行发布），然后从“Release type”下拉菜单中选择 wp，并在“WordPress major release”输入字段中输入 X.Y（例如 5.2）。最后，按下绿色的“Run workflow”按钮。这将触发 npm 发布任务，并且需要由 Gutenberg Core 团队成员批准。找到当前发布的 “Publish npm packages” action，并将其批准。

供参考，手动流程如下所示：

  1. 检出之前使用的 WordPress 分支（例如 wp/5.2）。
  2. git pull。
  3. 使用 npm ci 安装 npm 依赖项。
  4. 运行 npm exec --no -- lerna publish patch --no-private --dist-tag wp-5.2 命令（更多详情见 package release process），但当被要求为每个包选择版本号时（假设包版本采用这种格式 major.minor.patch），确保只提升 patch 版本号。例如，如果该 WordPress 分支上次发布的包版本是 5.6.0，则选择 5.6.1 作为版本。

注意：对于 WordPress 5.0 和 WordPress 5.1，使用了不同的发布流程。这意味着在为这两个版本选择 npm 包版本时，无法使用下一个 patch 版本号，因为它可能已被使用。您应该为此类情况使用“metadata”修饰符。例如，如果该 WordPress 分支上次发布的包版本是 5.6.1，则选择 5.6.1+patch.1 作为版本。

  1. 可选地，用新发布的版本更新已发布包的 CHANGELOG.md 文件，并提交到相应的分支（例如 wp/5.2）。
  2. 如果有 CHANGELOG 更新的提交，将其挑选（cherry-pick）到 Gutenberg 的 trunk 分支中。

现在，npm 包应已准备就绪，可以创建补丁并提交到相应的 WordPress SVN 分支。

独立错误修复包发布

当需要在常规发布周期之外将包含错误修复或安全版本的包发布到 npm 时，需要遵循以下工作流。

注意：trunk 和 wp/latest 分支均受限制，只能由 Gutenberg Core 团队进行 推送。

识别需要从仓库 trunk 分支移植到 wp/latest 的拉取请求对应的提交哈希值。

现在需要准备 wp/latest 分支以向 npm 发布和推送包。

打开终端并执行以下步骤：

  1. git checkout trunk
  2. git pull
  3. git checkout wp/latest
  4. git pull

在移植提交之前，检查 wp/latest 分支是否没有任何等待发布的未完成包：

  1. git checkout wp/latest
  2. npm ci
  3. npm exec --no -- lerna updated

现在将提交从 trunk 挑选（cherry-pick）到 wp/latest，如果该提交是拉取请求合并提交，请使用 -m 1 commithash：

  1. git cherry-pick -m 1 cb150a2
  2. git push

在等待 wp/latest分支的 GitHub actions 构建通过的同时，识别并开始更新 CHANGELOG.md 文件：

  1. git checkout wp/latest
  2. npm ci
  3. npm exec --no -- lerna updated
    示例：
    npm exec --no -- lerna updated
@wordpress/e2e-tests
@wordpress/jest-preset-default
@wordpress/scripts
lerna success found 3 packages ready to publish

检查当前 CHANGELOG.md 文件中列出的版本，浏览某个包的提交历史，例如 @wordpress/scripts，留意 “chore(release): publish” 和 “Update changelogs” 提交以确定最近的版本升级，然后查看自最近一次发布以来的提交，有助于发现自上次发布以来发生了哪些更改。

注意：您可能会发现每个包的当前版本不是最新的，如果是这样，更新以前发布的版本将不胜感激。

现在，wp/latest 分支已准备好发布 npm 包。要启动此过程，请前往 Gutenberg GitHub 仓库的 Actions 选项卡，找到 “Publish npm packages” action。注意显示“This workflow has a workflow_dispatch event trigger.”的蓝色横幅，并展开其右侧的“Run workflow”下拉菜单。

npm 发布的 Run workflow 下拉菜单

要发布包含错误修复的 npm 包，请从“Release type”下拉菜单中选择 bugfix，并保持“WordPress major release”输入字段为空。最后，按下绿色的“Run workflow”按钮。这将触发 npm 发布任务，并且需要由 Gutenberg Core 团队成员批准。找到当前发布的 “Publish npm packages” action，并将其批准。

在幕后，其余过程通过 npm exec --no release-cli -- npm-bugfix 命令自动完成。供参考，手动流程非常接近以下步骤：

  1. 检出 wp/latest 分支。
  2. 用计算出的新发布版本更新包的 CHANGELOG.md 文件，并提交到 wp/latest 分支。
  3. 通过控制台登录 npm：npm login。请注意，您应该启用了 2FA。
  4. 从 wp/latest 分支，使用 npm ci 安装 npm 依赖项。
  5. 运行脚本 npm exec --no -- lerna publish --no-private。
    • 当被要求为每个包选择版本号时，请选择更新后的 CHANGELOG 文件中的值。
    • 系统会多次询问您的一次性密码（OTP）。这是来自您使用的双因素认证（2FA）应用的代码。根据要发布的包数量，可能会要求提供多个 OTP，因为它们往往在发布完所有包之前就已过期。
    • 如果发布过程最终未完成（可能是因为超时或输入了错误的 OTP），请在恢复前通过 npm exec --no -- lerna publish from-package 检查 npm 状态。请参阅从部分 npm 发布中恢复。
  6. 最后，既然 npm 包已经发布，请将 lerna 创建的提交（“Publish”和 CHANGELOG 更新）挑选（cherry-pick）到 Gutenberg 的 trunk 分支中。

开发版发布

如同步 Gutenberg 插件一节所述，包的发布每两周从 wp/latest 分支进行一次。也可以使用开发版发布随时测试 trunk 分支中即将到来的更改。我们利用包分发标签，使得能够按照 npm 指南消费代码库的未来版本：

默认情况下，latest 标签由 npm 用于标识包的当前版本，并且 npm install <pkg>（不带任何 @<version> 或 @<tag> 指定符）安装的是 latest 标签。通常，项目仅对稳定发布版本使用 latest 标签，而对预发布等不稳定版本使用其他标签。

在我们的案例中，我们对代码使用 next 分发标签。想要安装此类版本的开发者需要输入：

npm install @wordpress/components@next

为了启动 npm 包的开发版发布流程，请前往 Gutenberg 的 GitHub 仓库的 Actions 选项卡，并找到“Publish npm packages” action。请注意显示“This workflow has a workflow_dispatch event trigger.”的蓝色横幅，并展开其右侧的“Run workflow”下拉菜单。

npm 发布的 Run workflow 下拉菜单

要将开发包发布到 npm，请从“Release type”下拉菜单中选择 development，并将“WordPress major release”输入字段留空。最后，点击绿色的“Run workflow”按钮。这会触发 npm 发布作业，且该操作需经 Gutenberg Core 团队成员批准。找到当前的“Publish npm packages” action，并将其批准。

在幕后，发布流程完全通过 npm exec --no release-cli -- npm-next 命令自动化。它确保
wp/next 分支与为 Gutenberg 插件创建的最新发布分支（release/X.Y）保持同步。为避免版本冲突，开发版发布包含时间戳，例如，@wordpress/block-editor@5.2.10-next.v.202607130915.0。