When the documentation still puts spec.running, deprecated 2 years ago, on the very first line: How a KubeVirt user guide PR was merged in ten days

Result: Merged (2026-10-27 00:04, kubevirt/user-guide#1040). In fact, this was taken from GitHub PRs, reviews, comments, timelines, inspection records, related issues and PRs, user guide source (the base commit of the PR 0ca33477), KubeVirt source (tag v1.9.0), the draft of the contribution ledger, and the VM creation code in the TT Lab repository. Times are in Korea Standard Time (KST).

Table of Contents

• One-line Summary
• 1. What was the problem: Warnings appear, but the documentation is silent
• 2. Cause: Which lines in the documentation
  • Run Strategies page
  • Architecture page
• 3. What was changed: Summary of the diff
• 4. Response: approve in 1 hour 37 minutes, lgtm in 9 days
• 5. What we learned: Tips for open-source contribution
• Links

One-line Summary

1. What was the problem: Warnings appear, but the documentation is silent

VirtualMachines in KubeVirt used to determine whether to turn a VM on or off using the boolean field spec.running , and now determine it using spec.runStrategy(Always·Halted·Manual· RerunOnFailure , etc.). spec.running was marked as kubevirt/kubevirt#12578(merged on 2024-09-30) as deprecated, and also featured in the v1.4.0 release notes "Deprecation" section of the user guide.

The API makes this very clear. This was verified on a v1.9.0 cluster, as noted in the PR body.

• kubectl explain vm.spec.running shows Deprecated: VirtualMachineInstance field "Running" is now deprecated, please use RunStrategy instead. .
• virtualmachine-validator.kubevirt.io webhooks are hooked into VM creation and modification, and if spec.running is present, a warning spec.running is deprecated, please use spec.runStrategy instead. is returned (vms-admitter.go lines 175–178).

kubectl explain ). The output is only in the PR body; the original output file was not left in the ledger.

However, the first sentence of the Run Strategies page in the user guide was "VirtualMachines have a Running setting that determines whether to run the guest", and never mentioned its deprecation. Anyone who visited that page looking for runStrategy would learn about running: true in the very first paragraph and leave.

TT Lab also exhibits the same pattern. The code that creates student VMs (TT Lab repository backend/app/vms.py) still includes "running": True in the manifest, and reads whether it is running using that field as well. The comment right above it states: "running is deprecated, and it is right to migrate to runStrategy, but we leave it as is to match the behavior of currently running VMs." The contribution ledger also notes that "TT Lab creates and reads student VMs using a deprecated field, same topic as this PR," and the migration task has been filed separately. As of 2026-10-29, it has not yet been migrated. We honestly record that while fixing someone else's documentation, our own code also carries the same debt.

2. Cause: Which lines in the documentation

Line numbers are based on the PR's base commit 0ca33477 .

Run Strategies page

• docs/compute/run_strategies.md Lines 5–12: Running Introduces the setting first, explains cases where it is not enough, and then moves on to RunStrategy. There is no mention of deprecation.
• Line 47: associated ith the VM Typo.

Architecture page

• The example VM on this page was changed in #849(merged on 2024-10-30, "Refer to spec.running as runStrategy") to runStrategy: Halted . However, the three surrounding sentences remained unchanged. Lines 195–197(「spec.running if true is true, recreate"), Line 357(「spec.running if false is false, VMI is not created"), Line 388(kubectl describe output of Running: true).
• Line 367 is virtctl start vm vm-cirros . virtctl start takes only a single VM name (start.go lines 46–49, v1.9.0).
• Halted VM when virtctl start changes runStrategy to Always (lifecycle.go lines 632–649, v1.9.0). Therefore, the describe output after starting should be Run Strategy: Always .

Attempts to fix this deprecation have been made before. Issue #923(2025-09-15) suggested fixing the VM lifecycle and RunStrategy documentation, and PR #927(2025-09-17) included deprecation notices alongside unrelated tolerations changes. Both were closed as inactive by a bot without reviews (2026-02-14, 2026-03-22).

3. What was changed: Summary of the 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

The explanation was not deleted. The existing explanation that "a single boolean cannot express cases of turning off inside the guest" is a good paragraph explaining why runStrategy came to be, so it was moved below "Old manifests use spec.running ". In addition, the opening sentence encountered by new users was changed to runStrategy, and a mapping table from the old field to the new field (true → Always, false → Halted) along with the warning message generated by the API server were placed in a warning box. Including the exact warning message is intended to help users find this page via search.

At the end of the PR body, it was noted that #923 and #927 covered the same topic but were closed before review, and that this PR only dealt with deprecation. The use of AI was disclosed in the commit trailer Co-Authored-By: Claude Opus 5.5 and Signed-off-by, and a single sentence at the end of the body: "Drafted with the help of AI and reviewed by myself." This conforms to KubeVirt's AI contribution policy. The commits are SSH-signed. The documentation build (mkdocs) was not run locally; Netlify previews were generated before merging.

4. Response: approve in 1 hour 37 minutes, lgtm in 9 days

There are no test jobs running per PR in this repository, so the needs-ok-to-test label remained until the end, but it did not affect the merge (ledger record). The remaining checks were DCO, Netlify preview, and tide. What was needed were human /approve and /lgtm , and the first one arrived immediately.

During the 9 days when the second one did not arrive, we noted in the ledger "Let's do /cc if it's quiet around 10/26" and waited. We asked once that day, and 6 hours and 35 minutes later, /lgtm arrived.

Later we found out that the maintainer who gave /lgtm was the person who opened issue #923 a year ago. It appears the PR reached someone who already knew about the same problem and was waiting for someone to fix it. Linking #923 in the PR body also likely made that connection easier.

5. What we learned: Open-source contribution tips

• 「Deprecations make the documentation echo what the API says.」 kubectl explain and webhook warnings were already saying the same thing. Copying that exact phrasing into the documentation allows users to find the documentation by searching for the warning, and frees maintainers from having to verify if the phrasing is correct.
• 「When fixing examples, check the surrounding sentences too." #849 changed only the YAML of the example while leaving the sentences explaining that YAML. Code blocks and the text immediately preceding and following them must be read as a single unit to spot mismatches. The virtctl command in the same spot was found this way.
• 「Narrow the scope by looking up previous attempts." #927 was bundled with unrelated changes and failed to get reviewed. This PR stated clearly in the body that it dealt solely with deprecation. Linking previous issues in the body may also notify people who remember those issues.
• 「Apply fixes to our own code as well." TT Lab's VM creation code still uses spec.running . Apart from fixing the upstream documentation, migrating our own code to runStrategy remains homework.

Titi's wrap-up. The playground sign used to say on the very first line, "Turn on the swing with the red button." But when you press the red button, a voice says, "This button will soon be gone, please use the blue handle." For two years! We changed the first line of the sign to the blue handle, and moved the story about the red button to the "Formerly" section. After waiting nine nights, the teacher who wrote a note a year ago saying "Please fix the sign" came by, said "Welcome!", and stamped it. But our playground swing is still turned on with the red button. We'll fix that soon.

Links

All materials were accessed on 2026-10-29.

• PR: kubevirt/user-guide#1040 (Merge commit a30126d0)
• Fixed documentation (base commit): run_strategies.md, architecture.md
• KubeVirt source (v1.9.0): vms-admitter.go, start.go, lifecycle.go
• Deprecation: kubevirt/kubevirt#12578
• Previous attempts: Issue #923, PR #927, Example fix #849