Kubevirt AI-generated issues

.cspell.yml

@@ -100,3 +100,8 @@ words:
   - yaspeller
   - kubevirt
   - viewports
+  - rniw
+  - zstd
+  - vmexport
+  - numa
+  - uefi

analyses/2026/kubevirt/issues-coverage.md

@@ -0,0 +1,19 @@
+# Issue coverage report
+
+This report maps every recommendation in
+`.github/input/ai-ranked-recommendations.csv` to the numbered issue files in
+`.github/output/issues/`. It is kept outside the issues directory so it is not
+uploaded as an issue.
+
+This data contains tables with long line lengths. See
+[issues-coverage.md](https://github.com/iRaindrop/kubevirt-work/blob/main/.github/output/issues-coverage.md)
+in iRaindrop/kubevirt-work.
+
+## Counts
+
+- Recommendations: 114
+- Recommendations turned into issues: 110
+- Recommendations skipped as not an issue: 4 (88, 94, 96, 110)
+- Standalone issue files written: 60 (9001–9060)
+- Umbrella issue files written: 12 (9061–9072)
+- Standalone issues not in an umbrella: 0

analyses/2026/kubevirt/issues/9001-add-getting-started-page.md

@@ -0,0 +1,52 @@
+---
+title: Add a Getting Started page after Architecture #9001
+labels: [high, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+A new user who has a working cluster has no single page that leads from
+installation to a running VirtualMachine. The path is spread across
+Installation, `virtctl`, Basic Use, and Lifecycle, so readers must assemble it
+themselves. The Quickstarts page also has no introduction that explains what it
+offers.
+
+Add a `docs/getting_started.md` page and place it immediately after Architecture
+in `docs/.nav.yml`. The page walks the reader through one happy path and links
+to the detailed page at each step:
+
+1. Install KubeVirt (link to Installation).
+2. Install `virtctl` (link to the `virtctl` page).
+3. Create a VirtualMachine from a provided manifest or with `virtctl create vm`.
+4. Start the VirtualMachine.
+5. Connect with `virtctl console`.
+6. Stop the VirtualMachine.
+
+Add a "Try it in a sandbox" section that links to, or folds in, the Quickstarts
+page. Give the Quickstarts page a one-paragraph introduction that states the
+prerequisites (a laptop with virtualization enabled, or a browser for
+Killercoda), the expected time, and what the reader has at the end. Close that
+page with a link back to Getting Started.
+
+## What you expected
+
+A new user opens one page after Architecture and reaches a running, accessible
+VirtualMachine by following numbered steps. The Quickstarts page states its
+prerequisites and outcome up front.
+
+## URL
+
+- https://kubevirt.io/user-guide/ (new page after Architecture)
+- https://kubevirt.io/user-guide/quickstarts/
+- `docs/.nav.yml`, `docs/quickstarts.md`, and the new `docs/getting_started.md`
+
+## Additional context
+
+Reuse the manifest from #9002 in step 3 so the two pages do not drift. If you
+fold Quickstarts into the new page, add a redirect in `mkdocs.yml`.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md

@@ -0,0 +1,52 @@
+---
+title: Rewrite Basic Use as "Your first VirtualMachine" #9002
+labels: [high, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+The Basic Use page presents `VirtualMachineInstance` commands
+(`kubectl create -f vmi.yaml`) without providing the `vmi.yaml` file. It treats
+the VirtualMachineInstance as the primary object, while most users manage a
+VirtualMachine, which creates and owns the running instance. The Lifecycle page
+repeats the undefined `vmi.yaml` reference.
+
+Rewrite `docs/user_workloads/basic_use.md` as a short "Your first
+VirtualMachine" page:
+
+- Introduce VirtualMachine as the primary object and VirtualMachineInstance as
+  the running instance it manages.
+- Include a complete minimal `vm.yaml` that uses a public containerDisk image.
+- Show `kubectl apply -f vm.yaml`, `virtctl start`, `virtctl console`, and
+  `virtctl stop`.
+- End with explicit links to the next pages, for example Creating
+  VirtualMachines, Accessing Virtual Machines, and Lifecycle.
+
+Update `docs/user_workloads/lifecycle.md` so its examples use the same `vm.yaml`
+manifest instead of the undefined `vmi.yaml`. Rename the page title and the
+`.nav.yml` entry in `docs/user_workloads/.nav.yml` if the file name changes, and
+add a redirect in `mkdocs.yml`.
+
+## What you expected
+
+A new user copies one manifest, runs four commands, and sees a VirtualMachine
+start, accept a console connection, and stop. The Lifecycle page continues from
+that same manifest.
+
+## URL
+
+- https://kubevirt.io/user-guide/user_workloads/basic_use/
+- https://kubevirt.io/user-guide/user_workloads/lifecycle/
+- `docs/user_workloads/basic_use.md`, `docs/user_workloads/lifecycle.md`
+
+## Additional context
+
+The Getting Started page in #9001 reuses this manifest, so write the two pages
+together or agree on the manifest first. Convert the commands to fenced blocks
+as you write them (see #9007).
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md

@@ -0,0 +1,42 @@
+---
+title: Add a Start here link and fix the Slack link on the Welcome page #9003
+labels: [urgent, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+The Welcome page lists sections but does not tell a first-time reader where to
+begin. It also shows the Slack channel as a raw URL
+(`https://kubernetes.slack.com/messages/virtualization`). Readers who are not
+yet in the Kubernetes Slack workspace cannot open that link, and the page does
+not name the channel.
+
+Edit `docs/index.md`:
+
+- Add a one-line "New to KubeVirt? Start here" link at the top that points to
+  the Getting Started page.
+- Replace the raw Slack URL with the channel name (`#virtualization`) and a link
+  to the Kubernetes Slack invitation page, so readers can join the workspace
+  first.
+
+## What you expected
+
+A new reader sees a "Start here" link before the section list and can reach the
+first-run path in one click. The Slack entry names the channel and explains how
+to join the workspace.
+
+## URL
+
+- https://kubevirt.io/user-guide/
+- `docs/index.md`
+
+## Additional context
+
+Depends on #9001, which creates the Getting Started page that the new link
+targets. Link to the page's final URL once it exists.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9004-restructure-installation-page.md

@@ -0,0 +1,47 @@
+---
+title: Restructure the Installation page around the core procedure #9004
+labels: [urgent, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+The Installation page buries the core install procedure among platform-specific
+and historical material. It covers AppArmor, kernel and user-land compatibility,
+SELinux, OKD, k3OS, daily developer builds, deploying from source, network
+plugins, and node placement. It also keeps notes about behavior before v0.20.0
+and v0.34.2. A new user cannot tell which steps are required.
+
+Restructure `docs/cluster_admin/installation.md`:
+
+- Put the core procedure first: Requirements, the four-command operator install,
+  verification, and the emulation fallback.
+- Move the topics listed above under a "Platform-specific and advanced
+  installation" heading, or split them into separate pages in
+  `docs/cluster_admin/` and add them to `docs/cluster_admin/.nav.yml`.
+- Remove the historical notes about v0.20.0 and v0.34.2, or move them to a
+  footnote. Does any supported upgrade path still require them?
+- End the page with a "Next steps" section that links to installing `virtctl`,
+  Creating VirtualMachines by using virtctl, and Accessing Virtual Machines.
+
+## What you expected
+
+The first screen of the page contains the steps needed to install KubeVirt and
+verify the result. Advanced and platform-specific topics are clearly separated,
+and the page ends with links to the next tasks.
+
+## URL
+
+- https://kubevirt.io/user-guide/cluster_admin/installation/
+- `docs/cluster_admin/installation.md`, `docs/cluster_admin/.nav.yml`
+
+## Additional context
+
+The "Next steps" link to installing `virtctl` targets the page created in #9005.
+Coordinate with #9011, which removes legacy installation content from the same
+page.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md

@@ -0,0 +1,47 @@
+---
+title: Create an Installing virtctl page #9005
+labels: [high, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+The `virtctl` page, titled "Download and Install the virtctl Command Line
+Interface", does not cover all published client binaries. New users need
+`virtctl` for nearly every first task, and the page sits in the middle of the
+User Workloads list, far from Installation.
+
+Edit `docs/user_workloads/virtctl_client_tool.md`:
+
+- Rename the title to "Installing virtctl".
+- Use the theme's content tabs for Linux, macOS, and Windows, each with amd64
+  and arm64 downloads.
+- Add `pymdownx.tabbed` with `alternate_style: true` to `markdown_extensions` in
+  `mkdocs.yml` if it is not already enabled.
+- Include the `chmod +x` and `PATH` steps for each platform.
+- Move the page next to Installation, for example into `docs/cluster_admin/`, or
+  keep it in place and link to it from the Installation page's "Next steps"
+  section.
+- Add a redirect in `mkdocs.yml` if the file moves, and update `.nav.yml`.
+
+## What you expected
+
+A reader on any supported operating system and CPU architecture finds the right
+binary, makes it executable, and puts it on their `PATH` from one page. The page
+is easy to find from Installation.
+
+## URL
+
+- https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/
+- `docs/user_workloads/virtctl_client_tool.md`, `docs/user_workloads/.nav.yml`
+
+## Additional context
+
+The Installation restructure in #9004 links to this page from its "Next steps"
+section. Ask the maintainers which binaries the release process publishes so the
+tab list is accurate.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md

@@ -0,0 +1,41 @@
+---
+title: Enable code copy and search features in mkdocs.yml #9006
+labels: [urgent, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+The guide is command-heavy, but code blocks have no copy button and the search
+box has no suggestions, highlighting, or sharing. The `mkdocs-material` theme
+provides these as feature flags, and they are not enabled in `mkdocs.yml`.
+
+Add the following entries to the `theme.features` list in `mkdocs.yml`:
+
+- `content.code.copy` adds a copy button to every code block.
+- `search.suggest` shows completion suggestions while the reader types.
+- `search.highlight` highlights matched terms on the destination page.
+- `search.share` adds a button that shares a link to the current search.
+
+Build the site locally with `mkdocs serve` and confirm that the copy button
+appears on a code block and that search suggests and highlights terms.
+
+## What you expected
+
+Every code block has a copy button, and search suggests terms, highlights
+matches on the result page, and offers a shareable link.
+
+## URL
+
+- https://kubevirt.io/user-guide/ (all pages)
+- `mkdocs.yml`
+
+## Additional context
+
+The copy button works best once the shell prompt characters are removed from
+code blocks (see #9007). This is a small change and a good first contribution.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).

analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md

@@ -0,0 +1,53 @@
+---
+title: Convert shell code blocks to fenced blocks #9007
+labels: [backlog, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues
+---
+
+## Description
+
+Many pages use indented code blocks with a `$` prompt, for example
+`$ kubectl create -f vmi.yaml`. Readers cannot paste these commands without
+removing the prompt, indented blocks get no syntax highlighting, and the copy
+button does not skip the prompt. Long lines also force horizontal scrolling on
+mobile devices and are hard for screen readers to navigate.
+
+Convert the blocks in this order, one pull request per group:
+
+1. The new-user path: Installation, `virtctl`, Basic Use, and Lifecycle.
+2. The longest reference pages: Disks and Volumes and Export API.
+
+For each block:
+
+- Replace the indented block with a fenced block with the `shell` language tag
+  and remove the `$` prompt.
+- Move example output to a separate block, or add a `title="Output"` annotation.
+- Break commands longer than 100 characters over several lines with `\`
+  continuations so they do not need horizontal scrolling.
+
+## What you expected
+
+Commands on the converted pages paste directly into a terminal, and output is
+visibly separate from commands. No command line requires horizontal scrolling on
+a phone.
+
+## URL
+
+- https://kubevirt.io/user-guide/cluster_admin/installation/
+- https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/
+- https://kubevirt.io/user-guide/user_workloads/basic_use/
+- https://kubevirt.io/user-guide/user_workloads/lifecycle/
+- https://kubevirt.io/user-guide/storage/disks_and_volumes/
+- https://kubevirt.io/user-guide/storage/export_api/
+- Matching files under `docs/cluster_admin/`, `docs/user_workloads/`, and
+  `docs/storage/`
+
+## Additional context
+
+If #9002, #9004, or #9005 are in progress, convert those pages as part of the
+rewrite to avoid merge conflicts. Enabling the copy button is tracked in #9006.
+
+This issue tracks recommended changes resulting from an analysis of the KubeVirt
+documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/).
+The assistance request is tracked in
+[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343).