30 KiB
发布 @wordpress 软件包至 NPM
作为版本发布流程的一部分，所有 @wordpress 软件包都会发布到 NPM。当构建 Gutenberg 插件压缩包操作完成草稿版本的创建后，你可能会看到一条提示，要求具备相应权限的人员触发发布 npm 软件包操作。
这条提示存在误导性。你无需手动执行任何操作来发布 @wordpress 软件包至 NPM。该过程已实现自动化，会在发布说明正式发布后自动运行。
查看版本草稿
工作流完成后，你可以在 Gutenberg 发布页面找到版本草稿。该草稿会预填充基于此版本先前候选版（RC）的更新日志条目，以及后续精选至发布分支的任何更改。因此，当发布某个系列的首个稳定版本时，请删除所有仅作为参考信息的候选版标题，并将最新更改移至正确章节（详见下文）。
整理版本更新日志
整理更新日志的最佳时机是在候选版工作流首次创建时。此时会触发更新日志自动化流程，生成初始版本的更新日志。虽然该过程主要依赖自动化，但正如前文所述，其效果很大程度上取决于里程碑中 PR 的标签是否准确。
稳定版发布流程会提取各候选版的更新日志并整合至稳定版。但需特别注意：稳定版仅会保留首次生成的更新日志内容（即 RC1 发布时的版本），后续对 RC1 更新日志的修改将不会同步至稳定版。
这意味着如果你在发布 RC1 前就完成了整个更新日志的整理，那么除了后续 RC2 或 RC3 版本中少量需要追加至稳定版的内容外，稳定版发布时无需再额外整理更新日志。
当版本更新日志出现在草稿中后，请仔细审阅并编辑内容，确保其清晰准确。此环节不必急于求成，重点在于保证发布说明的条理性，你可以随时保存草稿后续继续完善。
若担心在整理更新日志期间他人无法获取候选版本，可通过 Slack 频道 #core-editor 分享发布构件，这样他人即可在你完善更新日志时使用候选版本。
以下是一些编写清晰简明更新日志的补充建议：
- 将
杂项分类下的所有条目移至更合适的章节 - 修正拼写错误并优化表述，确保面向插件用户或持续关注开发进展的受众时易于理解
- 适时创建新分组并调整 PR 归属
- 当多个 PR 关联同一任务时（如后续修正的 PR），尝试将其合并为单一条目。典型范例包括：为性能优化移除 Lodash 的系列 PR、用 Playwright 替代 Puppeteer 的端到端测试更新、或将公共组件迁移至 TypeScript 的相关工作
- 若关联 PR 集的子任务内容充实，可考虑采用嵌套列表进行组织
- 删除同一版本中相互抵消的 PR（即代码净变化为零的还原类 PR）
- 移除所有仅涉及移动端应用的 PR（唯一例外是同时影响网页端功能的移动端 PR）
- 若某子标题下仅列有一条 PR，则移除该子标题并将 PR 移至包含多条目的相邻子标题
撰写版本发布公告
版本管理员需依据谷歌文档模板起草版本发布公告。鉴于公告内容的特殊性，若事先达成共识，相关工作可拆分委托给团队成员完成。草案完成后需进行同行评审。
发布版本公告
内容准备就绪后，拥有make.wordpress.org/core发布权限的作者将创建新草稿并导入内容。公告需包含以下标签：
作者需开启公告的公开预览功能，并申请最终同行评审。这一流程符合make/core发布指南的要求。
最终发布应在稳定版于WordPress.org上线后进行，此举有助于外部媒体同步传播版本信息。
招募下个版本的志愿者
完成版本发布后，请在#core-editor Slack频道发布信息，招募负责下个Gutenberg版本的志愿者。
具体示例可参考此处。
创建次要版本
有时需要为插件创建次要版本（即X.Y.Z），通常用于快速修复严重回归问题或程序缺陷。虽然Backport to Gutenberg Minor Release标签常用于标识需纳入次要版本的PR，但作为版本协调员，您也可能通过Slack收到非正式通知。即便如此，仍需确保所有相关PR都正确标注。
需要注意：次要版本不会单独创建分支（例如release/12.5.0），而是以标签形式存在。
次要版本的发布流程与主插件版本基本一致（参见上文），但存在重要差异。请务必通读完整指南后再进行操作。
更新发布分支
次要版本应仅包含必要的特定提交。操作时需在本地检出前一个主要稳定版本（非RC版本）分支（如release/12.5），然后精选所需提交至该分支。
release/12.5分支精选了提交，但12.6.0-rc.1已发布，则需将相同提交精选至release/12.6分支，否则这些提交不会包含在后续12.6版本中！通常建议与下个版本的发布协调员协同处理此流程。
精选过程可通过npm run cherry-pick脚本自动化执行，但运行脚本时请确保使用Backport to Gutenberg Minor Release标签。
同时必须确保所有纳入的PR都已分配至该次要版本对应的GitHub里程碑。需注意：PR合并时会自动分配至下一个稳定版本的里程碑，因此您需要在GitHub中逐一手动调整PR的里程碑归属。
例如，若您正在发布12.5.4版本，所有精选至该版本的PR必须从12.6里程碑移除，并重新分配至12.5里程碑。
完成精选后，可移除PR上的Backport to Gutenberg Minor Release标签。
当稳定发布分支整理就绪且PR分配正确里程碑后，即可将分支推送至GitHub，并通过GitHub网站图形界面继续发布流程。
运行小版本发布
前往 Gutenberg 的 GitHub 仓库的 Actions 标签页，找到 “构建 Gutenberg 插件压缩包” 操作。现在，你需要仔细根据当前插件发布版本的信息选择下一步操作：
如果上一个发布版本是稳定版（X.Y.Z，例如 12.5.0、12.5.1 等），请将 Use workflow from 字段保留为 trunk，并在文本输入框中指定 stable。工作流将自动创建一个小版本，根据需要递增 z 值（x.y.(z+1)）。
但如果上一个发布版本是 RC 版本（例如 X.Y.0-rc.1），你需要在创建发布时手动选择稳定版本的发布分支（例如 12.5.0）。如果不这样做，工作流将发布下一个主要的稳定版本（例如 12.6.0），而这并不是你想要的。
为此，在运行工作流时，从 Use workflow from 下拉菜单中选择适当的 release/ 分支（例如 release/12.5），并在文本输入框中指定 stable。
为之前的稳定版本创建小版本
即使已经发布了更新的稳定版本，也可以为任何发布分支创建小版本。这可以用于任何之前的发布分支，从而更灵活地向用户提供更新。过去，用户必须等待下一个稳定版本，可能需要几天时间。现在，可以根据需要迅速将修复推送到任何之前的发布分支。
该过程与上述已有 RC 版本时的流程相同：选择一个之前的发布分支，输入 stable，然后点击 “Run workflow”。发布将在 Gutenberg 的 GitHub 发布页面和 WordPress 核心仓库的 SVN 中以 tag 的形式发布到 https://plugins.svn.wordpress.org/gutenberg/tags/。SVN 的 trunk 目录不会被修改。
重要提示： 在发布由 “构建插件压缩包” 工作流 创建的草稿时，请确保取消勾选 “Set as last release” 复选框。如果不小心勾选了，“将 Gutenberg 插件上传到 WordPress.org 插件仓库” 工作流 仍会正确将其作为标签（并且不会替换 trunk 版本） 上传到 WordPress 插件仓库的 SVN——工作流会执行一些版本计算以确定插件的发布方式——但你仍然需要在 GitHub 上通过将正确的发布设置为 latest 来修复状态，具体操作在 发布页面 上进行！
故障排除
发布草稿已创建，但内容为空/包含错误消息
如果你忘记将正确的里程碑分配给你精选的 PR，那么生成的更新日志可能不符合预期。
务必手动验证更新日志中显示的 PR 是否与精选到发布分支的 PR 一致。
此外，如果发布仅包含一个 PR，但未将该 PR 分配到正确的里程碑，则在生成更新日志时会显示错误。在这种情况下，你可以编辑发布说明，手动添加缺失的 PR 的详细信息（格式可参考之前的发布）。
如果由于某种原因里程碑已关闭，你可以为了发布的目的重新打开它。
发布草稿仅包含 1 个资源文件，而其他发布包含 3 个。
这是正常现象。发布草稿仅包含插件压缩包。只有在发布后，其他资源才会生成并添加到发布中。
是否需要将点发布版本发布到 WordPress.org？
是的。方法与主要的插件发布流程相同。你需要 Gutenberg 核心团队或 Gutenberg 发布团队的成员批准发布工作流。
发布过程未能将版本更新提交精选到
trunk分支。
首先，通过检查 trunk 上的最新提交是否包含版本更新提交来确认步骤失败。然后在发布分支上回退版本更新提交——使用命令 git revert --no-edit {commitHash}。最后，推送更改并重新开始发布过程。
Gutenberg 插件发布指南
快速参考
时间安排
- 在里程碑日期（通常为周三）发布 RC1 版本
- 下周三发布正式稳定版
常规发布流程
步骤 1：准备工作
- 使用模板创建发布工单（可选操作，但有助于逐步执行流程）
- 审核里程碑中的所有 PR 并添加适当标签（
[Type] Bug、[Type] Enhancement等） - 测试更新日志：
npm run other:changelog -- --milestone="Gutenberg X.Y"
步骤 2：构建发布版本
- 在 #core-editor Slack 频道发布公告
- 前往 GitHub Actions → 构建插件压缩包工作流
- 保持
Use workflow from选项为trunk（默认值） - 输入
rc（候选版本）或stable（正式版本） - 点击
Run workflow - 当GitHub Releases中生成发布草稿后，立即发布以继续工作流
- 仅限稳定版：等待团队批准上传至 WordPress.org——这是工作流的最后一步，用于将插件部署到插件目录（示例）
步骤 3：编辑发布说明
- 在GitHub Releases中找到草稿
- 清理更新日志：修正拼写错误，调整分类不当的条目，合并相关 PR
- 移除仅限移动端的更改和已回滚的 PR
步骤 4：撰写发布文章
- 使用谷歌文档模板
- 重点介绍本次发布的 3-5 项关键功能
- 稳定版发布后，在 make.wordpress.org/core 上发布文章
额外候选版本与次要版本 (X.Y.Z)
针对 RC1 后的紧急修复或主要版本间的关键错误修复：
遴选错误修复
- 新 RC 版本：使用标有
Backport to Gutenberg RC的 PR - 次要版本：使用标有
Backport to Gutenberg Minor Release的 PR - 切换到相应发布分支：
git checkout release/X.Y - 运行：
npm run other:cherry-pick "[Label Name]" - 在运行工作流之前，将 PR 重新分配到正确的里程碑（例如从
12.6改为12.5）
运行发布工作流
- 前往构建插件压缩包工作流
- 从
Use workflow from下拉菜单中选择发布分支 - 继续执行上述步骤 2-4
详细流程
发布 Gutenberg 插件稳定版的第一步是在 Gutenberg 代码库中创建工单。该工单模板名为 "Gutenberg Release"，包含从候选版本到更新日志整理、遴选代码、稳定版发布及发布文章的完整清单。Gutenberg 21.2 的工单就是一个很好的范例。
该清单可帮助您与参与发布流程的开发人员及其他团队协调，确保所有必要步骤均已完成，且所有人员都清楚时间安排和重要里程碑。
发布周期
Gutenberg 的主要版本大约每两周发布一次。当前及后续版本会在 GitHub 里程碑 中追踪，同时标注每个版本的发布日期。
在当前里程碑日期（也称为标记日期），Gutenberg 的首个候选版本（RC）将发布。这是插件的预发布版本，供插件作者和用户测试。如果发现任何回归问题，可以发布新的 RC 版本。
候选版本按增量方式编号，从 -rc.1 开始，然后是 -rc.2，依此类推。一旦首个 RC（RC1）发布，发布文章的准备工作随即启动。
RC1 发布一周后，基于最后一个 RC 及必要的回归修复创建稳定版本。稳定版发布后，发布文章将同步上线。
如果在插件的稳定版本中发现关键错误，可随时发布修补版本。
版本管理
每个主要的 Gutenberg 版本由一位版本管理员（也称为版本负责人）负责运作。该负责人或小型团队在更广泛的 Gutenberg 开发团队支持下，负责 Gutenberg 版本的发布工作。
版本管理员负责启动所有发布活动，任何对发布计划的更改都需要他们的批准。在紧急情况下或版本管理员无法参与时，其他团队成员可以采取适当行动，但应随时向版本管理员通报情况。
准备发布
插件发布流程大部分是自动化的，并在 GitHub 上进行。您无需在本地计算机上执行任何步骤。不过，建议在本地保留一份 Gutenberg 副本，用于准备更新日志、进行常规测试，以及应对可能需要多个候选版本的情况。关于这一点，后续会详细说明。
这里有一个11分钟的视频，演示了插件发布流程。如果您对该流程不熟悉，建议先观看视频。以下段落也记录了该流程，并提供了更详细的说明。
组织和标记里程碑 PR
- 确保所有 PR 都正确标记。
- 每个 PR 必须有一个以
[Type]为前缀的标签。
准备 Gutenberg 版本的第一步是组织所有分配给当前里程碑的 PR，并确保每个 PR 都正确标记。标签用于自动生成更新日志，更改 PR 上的标签比事后在发布部分重新组织现有更新日志要快得多。
要测试将在发布工作流中运行的更新日志自动化功能，您可以在本地 Gutenberg 副本中使用以下命令，并指定您正在处理的稳定版本里程碑：
npm run other:changelog -- --milestone="Gutenberg 16.2"
该命令的输出是所提供里程碑的更新日志，上述示例中是 Gutenberg 16.2。您可以将输出复制并粘贴到 Markdown 文档中，这样可以更方便地查看，并允许您跟踪每个 PR 的链接。
所有 PR 都应有一个以 [Type] 为前缀的标签以及子类别标签。两个最常见的标签是 [Type] Bug 和 [Type] Enhancement。在查看生成的更新日志时，请特别注意以下内容：
- 增强功能： 查找没有附加任何子类别的 PR。
- 错误修复： 同样查找没有附加任何子类别的 PR。
- 其他： 此部分中的 PR 没有任何标签。
根据需要更新每个 PR 的标签。您可以继续生成更新日志，直到您满意为止。现在，您可以开始候选版本工作流了。
运行发布工作流
- 在 #core-editor 中宣布您即将开始发布工作流。
- 运行 构建 Gutenberg 插件 Zip 工作流。
在开始之前，请在 #core-editor Slack 频道中宣布您即将开始工作流，并说明您是要发布 Gutenberg 的稳定版本还是候选版本。
然后转到 Gutenberg 仓库，点击 Actions 标签页，找到 构建 Gutenberg 插件 Zip 操作。注意蓝色的横幅，上面写着“此工作流有一个 workflow_dispatch 事件触发器。” 展开其右侧的“Run workflow”下拉菜单。
要发布插件的候选版本，请在文本字段中输入 rc。要发布稳定版本，请输入 stable。在每种情况下，按下“Run workflow”按钮。
这将触发一个 GitHub Actions (GHA) 工作流，该工作流将提升插件版本、构建 Gutenberg 插件 .zip 文件、创建发布草稿并附加插件 .zip 文件。这部分过程通常需要大约六分钟。工作流将出现在列表顶部，紧挨着蓝色横幅下方。完成后，工作流的状态图标将从黄色圆点变为绿色对勾。您可以通过点击工作流来查看更详细的视图。
排查发布问题
插件已成功发布至 WordPress.org 插件目录，但工作流却显示失败。
此类情况偶有发生，例如可参考该案例。
请务必确认以下事项：
- 插件在目录中功能正常
- ZIP 包内容（参见下载页面）完整无误（无明显文件缺失）
- Gutenberg SVN 仓库包含两次新提交（查看提交记录）：
trunk目录应包含 "Committing version X.Y.Z" 提交- 新增的
tags/X.Y.Z目录内容与trunk一致，且最新提交为 "Tagging version X.Y.Z"
最可能的情况是标签目录未能自动创建。这是已知问题，可通过手动操作修复。
请将 SVN_USERNAME、SVN_PASSWORD 和 VERSION 替换为实际值，或先将其设为全局环境变量：
# 检出代码库
svn checkout https://plugins.svn.wordpress.org/gutenberg/trunk --username "$SVN_USERNAME" --password "$SVN_PASSWORD" gutenberg-svn
# 进入本地目录
cd gutenberg-svn
# 若本地已存在代码库
# 且未执行检出操作，请确保更新至最新版本
svn up .
# 将当前主干内容复制至新标签目录
svn copy https://plugins.svn.wordpress.org/gutenberg/trunk https://plugins.svn.wordpress.org/gutenberg/tags/$VERSION -m 'Tagging version $VERSION' --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD"
操作过程中如需帮助，请及时向团队求助。
发布文档撰写
发布文档由发布经理主导，并依托古腾堡开发团队成员协作完成。该流程包含一系列顺序步骤，因涉及人员众多且需协调配合，需在发布候选版与正式版之间的时间窗口内严格执行。古腾堡正式版于每周三发布，距首个候选版间隔一周。
- 复制发布公告谷歌文档模板——周三至周五
- 选定发布亮点——周五至周一
- 亮点确定后向设计团队申请素材（图片、视频）——周五至周一
- 起草发布公告并申请同行评审——周一至周三
- 正式版发布后公开公告——周三
选定发布亮点
整理完更新日志后，下一步是选取若干重要变更作为发布公告的亮点。这些亮点通常聚焦于新功能与体验优化（包括性能与无障碍改进），也可包含重要的 API 变更或关键缺陷修复。
鉴于古腾堡涉及面广且每个里程碑周期会合并大量 PR，时有值得重点介绍的变更被疏漏。因此本环节需要发布经理与其他古腾堡开发团队成员协同完成。若不确定如何选择，可随时向团队成员寻求建议。
发布素材准备
发布公告需配置若干视觉素材。公告特色图片建议沿用上一版本使用的图片（媒体库中文件名应为 'gb-featured'）。
公告正文中的横幅可通过名为「Gutenberg What's New Banner」的同步模式插入。使用该模式后请将版本号更新为正确数值。
重点功能还需配套视觉素材。针对核心功能可向设计团队申请专业素材，其他功能若操作熟练也可自行制作。申请设计素材时，请在 Slack 的 #design 频道中提出请求，可参考15.8 版本申请范例。素材将存放于专为该版本创建的谷歌网盘文件夹中。
制作 WordPress 发布素材时，可使用动画（视频或 GIF）或静态图片展示亮点。参考往期发布公告的呈现方式，注意动画更适合演示操作流程，而直接的功能亮点用静态图片即可。创作过程中请避免使用版权素材，并移除浏览器画布中可见的插件标识。
创建候选发布补丁（代码拣选）
- 确保所有需要拣选的PR都标记有
Backport to Gutenberg RC标签。 - 在本地克隆的Gutenberg仓库中，切换到发布分支：
git checkout release/X.Y - 使用自动化脚本拣选所有已合并的PR：
npm run other:cherry-pick "Backport to Gutenberg RC"
在RC版本发布后、最终稳定版发布前，一些与发布相关的错误可能会被修复并提交到trunk分支。稳定版本不会自动包含这些修复。需要手动将这些修复纳入，这个过程称为代码拣选。
作为发布经理，您可能会通过以下几种方式了解到这些错误：
- 贡献者可能会在已关闭的PR上添加
Backport to Gutenberg RC标签。在发布最终版本前，请搜索这些PR。 - 您可能会在#core-editor Slack频道收到直接消息或通知，告知您需要纳入RC的PR。即使在这种情况下，也应在PR上添加
Backport to Gutenberg RC标签。
自动化代码拣选
代码拣选过程可以通过Gutenberg中包含的npm run other:cherry-pick "[Insert Label]"脚本自动完成。运行命令时需要使用Backport to Gutenberg RC标签，并确保所有需要拣选的PR都已分配该标签。
将Gutenberg仓库克隆到本地开发环境后，首先切换到发布分支：
git checkout release/X.Y
接下来，使用适当的反向移植标签拣选所有已合并的PR：
npm run other:cherry-pick "Backport to Gutenberg RC"
在后台，该脚本将执行以下操作：
- 拣选所有带有
Backport to Gutenberg RC标签的PR - 将它们添加到发布里程碑
- 将所有更改
git push到发布分支 - 在PR上添加评论，表明它已被拣选
- 从PR中移除
Backport to Gutenberg RC标签
以下是该过程的截图：
手动代码拣选
如果您需要逐个、逐步处理代码拣选，可以手动按照以下顺序操作。在检出相应的发布分支后：
- 使用
git cherry-pick [SHA]按时间顺序拣选每个PR。 - 完成后，使用
git push将更改推送到GitHub。 - 移除所有已拣选PR的
Backport to Gutenberg RC标签，并将里程碑更新为当前发布版本。
要查找拉取请求的[SHA]，请打开PR，您将在末尾附近看到“[用户名]将提交[SHA]合并到trunk”的消息。
如果拣选的修复值得在稳定版本发布前再发布一个候选版本，请按照上述说明创建一个。在#core-editor Slack频道中告知其他贡献者已发布新的候选版本。
发布版本
- 在发布草稿中，点击“发布版本”按钮。
- 如果发布稳定版本，需获得Gutenberg发布团队、Gutenberg核心团队或WordPress核心团队成员的批准，才能将新插件版本上传到WordPress.org插件仓库（SVN）。
- 上传后，确认可以从WordPress插件仪表盘下载和更新最新版本。
只有当您对发布草稿中的更新日志内容满意时，才点击“发布版本”按钮。
请注意，您无需更改按钮上方的复选框。如果您发布的是RC版本，“设置为预发布版本”将自动被选中；如果您发布的是稳定版本，“设置为最新版本”将被选中。
发布版本将为该版本创建一个git标签，发布版本，并触发另一个GHA工作流，其目的有两个：
- 使用您刚刚编辑的发布说明更新
changelog.txt； - 将新插件版本上传到WordPress.org插件仓库（SVN）（仅当您发布稳定版本时）。
最后一步需要Gutenberg发布团队、Gutenberg核心团队或WordPress核心团队成员的批准。这些团队在发布准备就绪时会收到通知邮件，但如果时间紧迫，您可以在#core-editor Slack频道中询问或通知Gutenberg发布团队以加速流程。建议在启动发布流程之前提前联系，以便有人准备好批准。找到新版本的“将Gutenberg插件上传到WordPress.org插件仓库”工作流，并批准它。
一旦获得批准，新版本的Gutenberg将对全球的WordPress用户可用。上传后，请确认可以从WordPress插件仪表盘下载和更新最新版本。
最后一步是在make.wordpress.org/core上撰写发布文章。您可以在下面找到一些相关提示。