当文档仍在第一行使用两年前已废弃的 spec.running 时：KubeVirt 用户指南 PR 在十天内合并的背后

结果：已合并（2026-10-27 00:04， kubevirt/user-guide#1040). 实际上，这些内容取自 GitHub 的 PR、评审、评论、时间线、检查记录以及相关的 issue、PR、用户指南源码（PR 的基础提交 0ca33477）、KubeVirt 源码（标签 v1.9.0）、贡献记录草稿以及 TT Lab 仓库的 VM 创建代码。时间均为韩国时间。

一句话总结
1. 问题所在：有警告，但文档却保持沉默
2. 原因分析：文档的具体哪一行
- Run Strategies 页面
- Architecture 页面
3. 修改内容：Diff 摘要
4. 反应：1 小时 37 分钟获得 approve，9 天获得 lgtm
5. 收获：开源贡献小贴士
链接

一句话总结


PR	kubevirt/user-guide#1040 `docs: mark spec.running as deprecated in favor of runStrategy`
修改内容	`run_strategies.md`（将介绍段落调整为优先介绍 runStrategy、添加废弃警告框、修正一处拼写错误）、 `architecture.md`（三处周围文本、 `virtctl` 一个命令）。新增 27 行，删除 15 行
反应	Approver 在 1 小时 37 分钟内 `/approve`. `/lgtm` 在 9 天后由另一位维护者伴随欢迎语
结果	PR 公开 10-17 00:51 → `/approve` 02:28 → `/lgtm` 10-27 00:04 → 合并后 30 秒，约 9 天 23 小时 13 分钟

1. 问题所在：有警告，但文档却保持沉默

KubeVirt 的 VirtualMachine 过去使用布尔字段 spec.running 来决定是否开启 VM，而现在则通过 spec.runStrategy(Always·Halted·Manual· RerunOnFailure 等字段来确定。 spec.running 在 kubevirt/kubevirt#12578（2024-09-30 合并）中被标记为废弃，并且也收录在用户指南的 v1.4.0 版本发布说明的“Deprecation”中。

API 明确指出了这一点。以下是在 PR 正文中记录的、于 v1.9.0 集群中确认的内容：

kubectl explain vm.spec.running 显示了 Deprecated: VirtualMachineInstance field "Running" is now deprecated, please use RunStrategy instead. 。
virtualmachine-validator.kubevirt.io Webhook 拦截了 VM 的创建和修改，如果包含 spec.running 则会返回警告 spec.running is deprecated, please use spec.runStrategy instead. （vms-admitter.go 第 175–178 行).

kubectl explain 的输出仅存在于 PR 正文中，贡献记录中未保留输出的原始文件）。

然而，用户指南的 Run Strategies 页面的第一句却是“VirtualMachine 有一个用于决定是否运行 guest 的 Running 设置”，并且从未提及过废弃。通过搜索 runStrategy 来访问该页面的用户，最终在第一段中学到的依然是 running: true 并带着它离开。

TT Lab 中也存在类似的情况。用于创建学员 VM 的代码（TT Lab 仓库 backend/app/vms.py）至今仍在清单中写入了 "running": True ，并且也通过该字段来读取运行状态。正上方的注释中写着：“running 已废弃，虽然应该迁移到 runStrategy，但为了保持与当前运行的 VM 行为一致，暂时保留原样。”贡献记录中也写道：“TT Lab 正在使用已废弃的字段来创建和读取学生 VM，这与本 PR 是同一主题”，而迁移工作则被单独搁置。截至 2026-10-29，仍未完成迁移。在此坦诚地记录下来，因为在修复他人文档的同时，我们自己的代码也背负着同样的债务。

2. 原因分析：文档的具体哪一行

行号以 PR 的基础提交 0ca33477 为准。

Run Strategies 页面

docs/compute/run_strategies.md 第 5–12 行: Running 首先介绍了设置，在解释了仅靠该设置尚显不足的情况后，过渡到了 RunStrategy。其中完全没有提及废弃。
第 47 行: associated ith the VM 拼写错误。

Architecture 页面

该页面的示例 VM 在 #849（2024-10-30 合并，“将 spec.running 引用改为 runStrategy”）中被改为了 runStrategy: Halted 。然而周围的三个句子却保持原样。第 195–197 行(「spec.running 若为 true 则重新创建”），第 357 行(「spec.running 为 false 因而未生成 vmi”），第 388 行(kubectl describe 输出中的 Running: true).
第 367 行是 virtctl start vm vm-cirros 。 virtctl start 仅接收一个 VM 名称（start.go 第 46–49 行，v1.9.0）。
Halted 对某个 VM 执行 virtctl start 时，runStrategy 会变为 Always （lifecycle.go 第 632–649 行，v1.9.0）。因此启动后的 describe 输出理应是 Run Strategy: Always 。

过去曾有人尝试修复这个弃用问题。Issue #923（2025-09-15）提出应修改 VM 生命周期和 RunStrategy 文档，而 PR #927（2025-09-17）则将弃用标记与无关的 tolerations 修改混在了一起。这两者均未经过评审，便被机器人自动关闭（2026-02-14、2026-03-22）。

3. 做了哪些修改：diff 要点

 # docs/compute/run_strategies.md, Overview
-VirtualMachines have a `Running` setting that determines whether or not
-there should be a guest running or not. ...
+VirtualMachines have a `spec.runStrategy` field that determines whether
+or not there should be a guest running, and what KubeVirt should do when
+the guest stops.
+
+Older manifests use the boolean `spec.running` field instead. ... (기존 설명은 이 문단으로 옮김)
+
+!!! warning
+    `spec.running` is deprecated since KubeVirt v1.4.0. Use
+    `spec.runStrategy` instead: `spec.running: true` corresponds to
+    `runStrategy: Always`, and `spec.running: false` corresponds to
+    `runStrategy: Halted`. The API server still accepts `spec.running`,
+    but returns the warning ... when a VirtualMachine that sets it is created or updated.
-    associated ith the VM.
+    associated with the VM.

 # docs/architecture/architecture.md
-If a VirtualMachineInstance reaches a final state but the `spec.running`
-equals `true`, ...
+If a VirtualMachineInstance reaches a final state but the
+`spec.runStrategy` equals `Always`, ...
-Since `spec.running` is set to `false`, no vmi will be created:
+Since `spec.runStrategy` is set to `Halted`, no vmi will be created:
-$ virtctl start vm vm-cirros
+$ virtctl start vm-cirros
-  Running:  true
+  Run Strategy:  Always

并没有删掉解释。“单个布尔值无法表达在 guest 内部关闭的情况”这一原有解释是说明 runStrategy 诞生原因的绝佳段落，因此将其移到了“旧清单使用 spec.running ”的后面。此外，将新用户首次接触到的语句替换为了 runStrategy，并将从旧字段迁移到新字段的对照表（true → Always, false → Halted）以及 API Server 发出的警告文案放入了警告框中。直接照抄警告文案是为了让用户通过搜索就能找到此页面。

PR 正文末尾提到，#923 和 #927 讨论过相同主题但在评审前被关闭，本 PR 仅处理弃用相关内容。AI 的使用通过提交说明尾部的 Co-Authored-By: Claude Opus 5.5 与 Signed-off-by，以及正文末尾的一句话“初稿借助 AI 编写并经本人审核”予以说明。这符合 KubeVirt 的 AI 贡献政策。提交附带了 SSH 签名。文档构建（mkdocs）未在本地运行，Netlify 预览在合并前生成。

4. 反应：approve 用时 1 小时 37 分钟，lgtm 用时 9 天

时间	天
10-17 00:51	PR 公开。prow 添加了 `needs-ok-to-test`·`size/M` 标签，指定了两位评审
10-17 02:28	approver 给出 `/approve`. `approved` 标签
10-26 17:29	由于连续 9 天没有 `/lgtm` ，@ 了一位其他维护者并请求 `/cc` “已有 approve，只差 lgtm 了”
10-27 00:04	该维护者给出 `/lgtm`，“感谢修复，欢迎来到该项目”
10-27 00:04	30 秒后 tide 合并

由于此仓库没有针对每个 PR 运行的测试任务， needs-ok-to-test 标签一直保留到了最后，但这并不影响合并（根据历史记录）。剩余的检查只有 DCO、 Netlify 预览和 tide 三项。所需的人工检查只有 /approve 和 /lgtm 两项，第一项很快就完成了。

在第二项迟迟未到的 9 天里，我们在记录中写下“如果 10/26 左右无人响应就 /cc ”并等待。当天请求了一次，6 小时 35 分钟后 /lgtm 到来了。

事后发现，给出 /lgtm 的维护者正是 1 年前开启 Issue #923 的人。PR 似乎正好触达了了解相同问题并一直在等待有人修复的人。在 PR 正文中提及 #923 似乎促成了这种连接。

5. 收获：开源贡献技巧

「弃用说明让文档与 API 保持一致。」 kubectl explain 与 Webhook 警告本就在传达相同的信息。将这些文案直接移植到文档中，用户搜索警告即可找到文档，而维护者也无需单独核实文案是否正确。
「修改示例的 PR 需兼顾周边的句子。”#849 仅修改了示例的 YAML，却保留了对该 YAML 进行说明的句子。代码块及其前后的句子必须作为一个整体来阅读，才能发现不一致之处。同一位置的 virtctl 命令也是通过这种方式找到的。
「通过寻找先前的尝试来缩小范围。”#927 因与无关的修改捆绑在一起而未得到评审。本 PR 在正文中明确说明仅处理弃用相关内容。在正文中附上先前的 Issue，可能会向记得该 Issue 的人发送通知。
「将修改应用到我们自己的代码中。”TT Lab 的 VM 创建代码目前仍在使用 spec.running 。除了修改上游文档之外，将我们的代码迁移到 runStrategy 是留下的功课。

TT 的简短感悟。 游乐场告示牌的第一行写着“秋千通过红按钮启动”。然而按下红按钮时，却传出了“此按钮即将取消，请使用蓝色把手”的声音。已经两年了！我们将告示牌第一行改成了蓝色把手，并将红按钮的故事移到了“过去”栏目。等待了九个夜晚后，一年前写过“请修复告示牌”纸条的老师来了，并盖下了“欢迎”的印章。不过我们游乐场的秋千目前也还在用红按钮启动。这一点我们很快就会修复。

链接

所有资料均于 2026-10-29 查阅。

PR： kubevirt/user-guide#1040 （合并提交 a30126d0)
修改的文档（基于提交）： run_strategies.md, architecture.md
KubeVirt 源码（v1.9.0）： vms-admitter.go, start.go, lifecycle.go
弃用： kubevirt/kubevirt#12578
先前的尝试：Issue #923，PR #927，修改示例的 #849