rhdh-plugin-midstream-propagate

RHDH 插件 → overlays → catalog 传播

在 redhat-developer/rhdh-plugins 中完成修复或功能后，按以下三步推进：

1. 在 rhdh-plugins 中更新变更，并包含一个 changeset；等待变更合并，并且新软件包发布到 npmjs.com（例如 @red-hat-developer-hub/backstage-plugin-app-defaults 0.0.3 以及同一时间发布的其他软件包）。
2. 更新 overlays 仓库（rhdh-plugin-export-overlays），获取与上述变更相关的 Version Packages PR 的提交 SHA。
3. 从该 SHA 提取具体变更，并将其推送到 rhdh-plugin-catalog；更新 overlay-repo/、workspaces/，以及对仅该工作区进行完整克隆时 sync-midstream.sh 会修改的其他路径；然后打开 MR，应用更新后的文件，并将 .tekton/ 中关联的 PLR 更新为适当的标签（例如 2.0.0--0.0.3）。

优先选择精准的 catalog MR，而不是运行 build/ci/sync-midstream.sh --force-clone <workspace>（耗时几分钟，而完整重新克隆/导出需要很长时间）。只有在必须重新生成导出内容、plugin_builds 注解或工作区转换时，才使用范围限定的 --force-clone。

仓库与配置

步骤	仓库	配置键
1	redhat-developer/rhdh-plugins	repos.plugins
2	redhat-developer/rhdh-plugin-export-overlays	repos.overlay
3	gitlab.cee.redhat.com/rhidp/rhdh-plugin-catalog	repos.catalog

按名称调用 /rhdh-context 并读取其报告的路径，以确定检出目录。若要直接运行其 CLI，请将 RHDH 设置为该 skill 的 scripts/rhdh 包装器，并使用点分隔的键："$RHDH" --json config get repos.<key> | jq -r '.data.value'（参见 references/catalog-surgical-update.md）。对 catalog MR 使用针对 gitlab.cee.redhat.com 的 glab（而不是 gitlab.com）。

打开 PR/MR 前，先确认 Jira 键。要附加问题链接，请按名称调用 skill /rhdh-jira-link。要打开 PR 或 MR 本身，请按名称调用 skill /rhdh-pr-create。只有在这两个 skill 均未安装时，才直接使用 gh / glab。

---

步骤 1 — rhdh-plugins（+ changeset → npm）

按照创建 changeset的说明，提交包含 changeset 的修复，合并机器人创建的 Version Packages PR，并等待该版本中的所有软件包发布到 npmjs.com。

**进入步骤 2 前的检查：**已发布的 npm 版本与 Version Packages 中的版本提升一致；npm view <pkg>@<ver> gitHead 等于 Version Packages 的合并 SHA。

可选：按名称调用 skill /rhdh-pr-create，以在 rhdh-plugins 中完成构建、changeset 和 PR。

---

步骤 2 — overlays（source.json → Version Packages SHA）

npm 发布后，按照 workspaces/<ws>/ 中的元数据同步说明操作：将 source.json 中的 repo-ref 设为 Version Packages 的合并 SHA（而不是更早的修复提交），同步 repo-backstage-version，并更新 metadata/*.yaml 中的版本以及同一版本中发布的每个软件包对应的 dynamicArtifact OCI 标签。

在处理 catalog 前，先合并 overlays PR。此后，catalog midstream 必须以 overlays 的 main（或你的发布分支）为目标。

注意：/rhdh-overlay 负责 overlays 仓库，包括通用的 source.json 版本提升；按名称调用它来修改工作区。此流程额外要求 repo-ref 必须是 Version Packages SHA。如果需求提及 Version Packages、promote-to-catalog 或 midstream，优先使用此 skill，而不是普通的 overlay 更新。

---

步骤 3 — 目录的中途手术式 MR

编辑前请阅读 references/catalog-surgical-update.md（路径、配置捕获、PLR 重新生成和限定范围的同步标志的单一事实来源）。

目标：刷新与对单个工作区执行 sync-midstream.sh --force-clone '<ws>' 时相同的一组文件，无需克隆所有工作区。

首选（手术式）

1. 从 overlays main 同步 overlay-repo/workspaces/<ws>/（source.json、plugins-list.yaml、metadata/，以及存在时的 overlays/patches）。
2. 将 $SHA 处的上游差异应用到 workspaces/<ws>/ — 至少包括根目录 package.json / yarn.lock（拥有锁文件的树）以及任何插件的 package.json 版本升级；如果 Version Packages 的变更不只是锁文件/元数据，则将范围扩展到插件源代码。不要只应用 plugins/<name>/ 下的锁定/解析固定项。
3. 对齐 plugin_builds/<ws>/*.json 中的 registryReference 标签（quay.io/rhdh/...:<rhdh>--<pluginVer>，例如 2.0.0--0.0.3）。
4. 更新相关的 .tekton/ PLR / Containerfile：
   • konflux.additional-tags → <xy>--<ver>,<x.y.z>--<ver>（例如 2.0--0.0.3,2.0.0--0.0.3）
   • DESCRIPTION 中的插件版本片段
   • 已知时，UPSTREAM_REPO 应指向 overlays 树的 SHA
   • 或通过 .tekton/updatePLRs.sh 重新生成受影响的 PLR（参见参考文档：嵌套结构使用 --path '<ws>/plugins/<plugin>'，扁平结构使用 --package；根据 source.json 中的 repo-flat 判定）
5. 通过调用指定技能 /rhdh-pr-create 创建目录 MR，或使用 glab 在 CEE GitLab 上创建。在正文中注明相关软件包的版本。当此技能为直接通过 glab 提交而编写正文时，在写入门禁前，对完整标题和正文以 flavored register 调用一次 /prose-editing。保留版本、SHA、软件包名称、标题、链接和命令。当最终由 /rhdh-pr-create 编写正文时，直接向其提供事实，无需编辑；该技能负责唯一一次文字润色。

**.tekton 的负责范围：**此技能仅负责与当前要晋升的工作区的手术式目录 MR 一同提交的工作区级 PLR 和 Containerfile 标签更新。整个目录范围内的完整流 PipelineRun 重新生成由 /rhdh-konflux-tasks 负责；应按名称调用该技能，而不是在此处重新生成整个流。

回退方案（限定范围的同步）

当需要执行导出 / 注释 / update-workspace.js 转换时，请使用 references/catalog-surgical-update.md 中的命令（不要在此处另行编造标志组合）。当差异已知（固定项、锁文件、版本）时，优先使用手术式方案。

---

外部写入

推送分支、发表评论、创建 overlays PR 和创建目录 MR 都属于外部写入：请调用指定技能 mutation-gate，并遵循该技能负责的门禁，不要在此处重复说明。晋升插件的请求代表意图，并不等于批准特定的推送。

---

检查清单

• rhdh-plugins 变更包含 changeset；Version Packages 已合并
• npm 软件包已发布；gitHead == Version Packages SHA
• overlays repo-ref + 元数据版本/OCI 标签已更新并合并
• 目录中的 overlay-repo/workspaces/<ws>/ 与 overlays 一致
• 目录中的 workspaces/<ws>/ 反映 $SHA 在拥有 yarn.lock 的根目录处的状态（按需更新锁文件/解析/版本）
• plugin_builds/ + .tekton/ 标签与新的插件版本一致（x.y.z--<pluginVer>）
• 已在 CEE GitLab 上创建目录 MR；已关联 Jira

示例（RHIDP-16097 / app-defaults）

步骤	工件
1	rhdh-plugins 修复 + changeset → Version Packages → @…/[email protected]（gitHead 18f4229…）
2	overlays PR 更新 workspaces/app-defaults/source.json + 元数据
3	目录 MR 同步 overlay-repo/…/app-defaults + 工作区根目录锁定项（手术式；不使用 --force-clone）

完成

当上述清单中的每个方框都已勾选，且每个步骤都经过独立验证、无需依赖上一步是否报告正确时，整个流程即告完成。

报告已发布的软件包版本及其解析到的 SHA、overlays PR 和 catalog MR 的 URL、它们关联的 Jira key，以及 catalog 变更是精确修改，还是回退到限定范围的 --force-clone。指出所有尚未完成的事项：仍在等待合并的变更、仍在发布流程中的 npm 发布、已交由 /rhdh-konflux-tasks 处理的流级别 PipelineRun 重新生成，或已声明但未经批准的外部写入。