结果：已合并（2026-10-28 01:03， kubeflow/trainer#4334），Issue #4310 已关闭，里程碑 v2.4。 内容实际上取自 GitHub 的 Issue、PR、评审、时间线与检查记录，Trainer 源码（PR 的基础提交
8e076764，以及标签 v2.1.0、v2.2.0、v2.3.0 的 Chart 值），Kubeflow 的 AI 政策文档， 以及贡献日志的草稿。时间均为韩国时间。
目录
一句话总结
| Issue | kubeflow/trainer#4310 Installation guide pins chart v2.1.0, so the runtimes and crds flags shown below it are silently ignored |
| PR | kubeflow/trainer#4334 fix(docs): use v2.3.0 in the installation guide |
| 变更内容 | 将安装文档与数据缓存文档中的 VERSION 更新为 v2.3.0，并新增了一条固定版本的运行时安装命令。新增 9 行，删除 3 行 |
| 反应 | 负责人在 Issue 中回复“升级到 v2.3 吧，要自己尝试修复吗？”，并在 PR 中 /ok-to-test·/lgtm·/approve 一气呵成 |
| 结果 | Issue 10-26 21:43 → 负责人回复 10-27 00:28 → PR 14:28 → 批准 10-28 00:02 → 合并 01:03。PR 用时约 10 小时 35 分钟，从 Issue 开始计算用时约 27 小时 20 分钟 |
1. 问题所在：被无声忽略的值
TT Lab 正在将乒乓球记分板的识别模型训练迁移到 Kubeflow 上，而 Kubeflow Trainer 正是用于在 Kubernetes 上运行这些训练作业的组件。
在阅读安装文档时，我们发现上下内容存在矛盾。行号以 PR 的基础提交 8e076764 为准。
docs/operator-guides/installation.md第 29 行:export VERSION=v2.1.0，并且 Helm 安装要求--version ${VERSION#v}.- 同一页面的 第 59–60 行和
第 69–71 行：如果要一起安装默认运行时
--set runtimes.defaultEnabled=true，如果要选择性安装则附加--set runtimes.torchDistributed.enabled=true等参数。 - 第 48 行：如果单独管理 CRD，
--set crds.enabled=false.
Chart 的 values.yaml 在各标签页中的情况如下。
| Chart 版本 | runtimes 键 |
crds 键 |
values.schema.json |
|---|---|---|---|
| v2.1.0 | 无 | 无 | 无 |
| v2.2.0 | 第 181 行 | 无 | 无 |
| v2.3.0 | 第 190 行 | 第 25 行 | 无 |
Helm 은 값 검증 스키마가 없는 차트에 모르는 키를 넘겨도 오류를 내지 않습니다. 그래서 문서를 그대로 따라 하면 2.1.0 제어부가 깔리고, ClusterTrainingRuntime 은 하나도 생기지 않으며, 왜 그런지 알려 주는 메시지도 없습니다.
这里还有另外两个分支问题。在使用 kustomize 安装的章节中，控制面使用了固定版本的命令（?ref=${VERSION}, 第 87 行），
而运行时却只有 ?ref=master 命令（第 96–99 行）。
“通过发布版本安装”的路径最终会将发布版本的 CRD 与 master 的运行时混用。在文档从 kubeflow.org 迁移到该仓库的文档站点之前（#3308），
这两条命令都是具备的。此外， docs/user-guides/data-cache.md 第 51 行
也写着 v2.1.0。
在此分点说明哪些进行了验证、哪些未进行验证。Chart 的值是通过直接打开各标签对应的文件确认的（见上表，2026-10-29 重新确认），并且 Chart 2.3.0 已上传至 OCI 仓库，
manifests/overlays/runtimes·data-cache 也存在于 v2.3.0 中，这些均已得到确认。不过，我们并未在实际集群中运行 Helm 和 kustomize 命令来亲眼观察 2.1.0 无法生成运行时的现象（未进行实测）。我们在 PR 的正文中也如实说明了这一点。
2. 为什么不直接提 PR，而是先从 Issue 开始
该仓库曾有过仅升级版本号的请求被拒绝的先例。2026-07-27 的 Issue #3807 “将 helm install VERSION 升级到 v2.2.1”在同一天被负责人以“README 中的版本仅为展示用户如何选择版本的示例”为由关闭了。
如果直接把相同内容提交为 PR，可能会因为同样的原因被关闭。因此在草稿阶段，我们确定了三件事（来自负责人的草稿备忘录）。
- 不直接提 PR，而是先开 Issue。
- 不把重点放在“版本过时”上，而是将“同一页面的命令在该版本中被悄悄忽略”的功能缺陷放在首位。明确提及 #3807，并指出本次情况的不同之处在于“示例版本并不具备该值，而同一页面的命令却依赖于它”。
- 不仅提出固定版本的方案，还同时提出保留示例版本、但为其加上“
runtimes.*自 2.2.0 起引入，crds.enabled自 2.3.0 起引入”注释的备选方案。 同时写明无论选择哪种都会提交 PR。
Issue #4310 于 2026-10-26 21:43 按照这种形式开启。它遵循了 Bug 报告模板的栏目顺序， 并在正文末尾添加了 AI 告知声明：“包括逐个标签页读取 Chart 值在内，Claude 协助完成了调查与草稿起草。”
2 小时 45 分钟后，负责人进行了回复。他表示应当将安装指南升级到 v2.3，并询问是否愿意亲自进行修复。并在同一条评论中附上了 /kind docs 和 /good-first-issue
标签。这相当于选择了两个方案中的第一个。
3. 修改了什么：diff 摘要
收到负责人回复的当天下午，我们开启了 PR。
# docs/operator-guides/installation.md
-export VERSION=v2.1.0
+export VERSION=v2.3.0
...
-Run the following command to deploy Kubeflow Trainer built-in runtimes
+Run the following command to deploy Kubeflow Trainer built-in runtimes:
+
+kubectl apply --server-side -k "https://github.com/kubeflow/trainer.git/manifests/overlays/runtimes?ref=${VERSION}"
+
+For the latest changes run:
kubectl apply --server-side -k "https://github.com/kubeflow/trainer.git/manifests/overlays/runtimes?ref=master"
# docs/user-guides/data-cache.md
-export VERSION=v2.1.0
+export VERSION=v2.3.0
运行时命令完全遵循了控制面命令已经采用的形式（固定版本的命令，其下方则是“最新更改请参考” master 命令）。我们没有触及在 #3807 中被关闭的那个文件——Chart 的 README，并在正文中引用了 #3807 作为理由。
PR 正文的“如何测试”一栏中写了以下内容。
- 在与
.readthedocs.yaml相同的条件（Python 3.12，将警告视为失败）下，于python:3.12-slim容器中构建了文档。make -C docs html SPHINXOPTS="-W --keep-going -q"在 master 和本次更改中均以退出码 0、无警告地完成，并且渲染出的两个页面中都能看到新命令。 git diff --check非常干净。.pre-commit-config.yaml中没有 Markdown 检验工具。- Helm·kustomize 명령 자체는 클러스터에 돌리지 않았습니다.
AI 的使用遵循了 Kubeflow 的 AI 政策。该政策要求：AI 生成的贡献必须在本地构建并测试后再提交；必须能够在评审中对其进行解释；需在 PR 正文或提交说明尾部（Assisted-by·Co-authored-by）中予以披露；并且 AI 不得自动回复维护者的反馈。我们在提交中附带了 Assisted-by: Claude 以及 DCO 签名，并在正文中设置了“AI assistance”段落，写明“Claude 协助查找并编写了更改草稿，上述验证也是在其帮助下运行的”。上述文档构建即对应政策要求的“本地确认”。该提交在 GitHub 上显示为未签名提交。
4. 反应：一夜之间完成合并
| 时间 | 日期 |
|---|---|
| 10-26 21:43 | 公开 Issue #4310。欢迎机器人发送“第一条 Issue”问候 |
| 10-27 00:28 | 负责人回复并公开 /kind docs·/good-first-issue |
| 10-27 14:28 | PR。自动注册至项目看板，指定两名评审人，打上 size/S 标签 |
| 10-28 00:02 | 负责人附上“Thanks!”并在一则评审中给出 /ok-to-test·/lgtm·/approve 批准 |
| 10-28 01:03 | 合并，Issue #4310 关闭，里程碑 v2.4 |
评审评论只有一句感谢。由于在 Issue 中已经确定了方向，所以在 PR 中似乎没有什么需要询问的。 ok-to-test 之后运行的 13 项检查全部通过，耗时最长的 test 为 58 分 42 秒。
我们没有在 Issue 中单独回复。虽然在日志中写了“由用户亲自回复 Issue”，但结果相当于第二天用 PR 进行了回复。 这也完全符合 Kubeflow AI 政策中“AI 不得自动回复维护者反馈”这一条款。
5. 收获：开源贡献小贴士
- 「先找出关闭的先例，并正面回应其理由。“README 中的版本仅为示例”——负责人这句话单看版本号而言是正确的。而本次 Issue 并未反驳这句话， 而是指出了另一个问题：“示例版本与同一页面的其他命令不符”。
- 「给出两个修复方案能让维护者更容易做出选择。是固定版本还是添加注释，取决于项目的文档方针。把两者都列出来并表示无论选哪个都会提交 PR 后， 负责人用一句话做出选择并将工作交给了我们。
- 「“会被悄悄忽略”通过一张表格就能一目了然。列出了三个标签的
values.yaml中键出现行号的表格，无需在集群中进行复现就能展示问题。 我们在文中也单独注明了“未在集群中实际运行”这一点。 - 「文档 PR 同样使用项目的构建条件进行测试。由于 Read the Docs 将警告视为错误进行配置，我们在本地使用相同条件先行构建。在文档 PR 中，这就是对 AI 政策要求的“本地确认”最好的诠释。
TeeTee 的碎碎念。 如果食谱的第一行写着“请拿出 2.1 版本的锅”，而几行之后又写着“请按下锅的蒸煮按钮”。但是 2.1 版本的锅根本没有蒸煮按钮！就算模仿着去按，锅也不会有任何反应，晚餐也就吃不上小笼包了。当我们去询问“是要把锅升级到新版本，还是写上一句‘蒸煮按钮从 2.2 版本开始才有’呢？”时，大厨回答说：“那就升级版本吧，你要不要自己来修修看？”第二天早晨，修好的食谱就已经插在书架上了。
链接
所有资料均于 2026-10-29 查阅。
- Issue： kubeflow/trainer#4310
- PR： kubeflow/trainer#4334 （合并提交
92f88b47) - 修改的文档（基础提交）：
installation.md,data-cache.md - Chart 值： v2.1.0, v2.2.0, v2.3.0
- 先例：Issue #3807
- Kubeflow AI 政策： https://github.com/kubeflow/website/blob/master/content/en/docs/about/ai_policy.md