From 5936bb1b60b3cf5eb7b684790e4b538f360f99f7 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Sun, 11 Oct 2026 23:28:14 -0700 Subject: [PATCH 01/31] added files Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 171 ++++++++++++++++++ ...cs-and-build-configuration-improvements.md | 42 +++++ ...on-contributor-guide-and-review-process.md | 85 +++++++++ ...-create-a-new-user-getting-started-path.md | 70 +++++++ ...s-and-maintain-a-beginner-issue-backlog.md | 45 +++++ ...-ownership-and-documentation-boundaries.md | 55 ++++++ ...del-and-publish-versioned-documentation.md | 43 +++++ ...t-v1-9-features-and-add-reference-pages.md | 50 +++++ ...-on-the-user-guide-and-fix-broken-links.md | 29 +++ ...compliance-seo-and-adopter-content-gaps.md | 78 ++++++++ ...and-reorganize-information-architecture.md | 64 +++++++ ...bility-mobile-usability-and-code-blocks.md | 76 ++++++++ ...cy-branch-names-and-minimizing-language.md | 50 +++++ .../add-a-user-facing-troubleshooting-page.md | 35 ++++ ...d-repository-files-into-cncf-compliance.md | 32 ++++ 15 files changed, 925 insertions(+) create mode 100644 analyses/2026/kubevirt/issues-coverage.md create mode 100644 analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md create mode 100644 analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md create mode 100644 analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md create mode 100644 analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md create mode 100644 analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md create mode 100644 analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md create mode 100644 analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md create mode 100644 analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md create mode 100644 analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md create mode 100644 analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md create mode 100644 analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md create mode 100644 analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md create mode 100644 analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md create mode 100644 analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md new file mode 100644 index 00000000..61ddfc7f --- /dev/null +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -0,0 +1,171 @@ +# Issue coverage report + +This report maps every recommendation in `.github/input/ai-ranked-recommendations.csv` to the issue file in `.github/output/issues/` that covers it. It is kept outside the issues directory so it is not uploaded as an issue. + +## Issue files + +| File | Label | Sub-issues | +|---|---|---| +| `U-create-a-new-user-getting-started-path.md` | urgent | 6 | +| `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | urgent | 7 | +| `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | urgent | 4 | +| `U-document-v1-9-features-and-add-reference-pages.md` | high | 6 | +| `add-a-user-facing-troubleshooting-page.md` | high | standalone | +| `U-improve-accessibility-mobile-usability-and-code-blocks.md` | high | 9 | +| `U-remove-legacy-branch-names-and-minimizing-language.md` | high | 6 | +| `U-build-a-documentation-contributor-guide-and-review-process.md` | urgent | 9 | +| `U-document-the-versioning-model-and-publish-versioned-documentation.md` | high | 5 | +| `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | urgent | 5 | +| `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md` | urgent | standalone | +| `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | urgent | 10 | +| `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | high | 3 | +| `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | high | 7 | + +## Recommendation mapping + +| # | Section | Area | CSV priority | Issue file | Sub-issue | +|---|---|---|---|---|---| +| 1 | Project Documentation | Information architecture | 2 - High | `U-create-a-new-user-getting-started-path.md` | Add a Getting Started page after Architecture | +| 2 | Project Documentation | Information architecture | 2 - High | `U-create-a-new-user-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | +| 3 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add the Plugins page to the navigation and delete the duplicate page | +| 4 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md`
`U-document-v1-9-features-and-add-reference-pages.md`
`U-document-v1-9-features-and-add-reference-pages.md` | Document the VirtualMachineBackup API
Document the CrossArchitectureVirtualization feature gate
Document masquerade PortRanges and MigrationPolicy compression | +| 5 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Create a virtctl command reference | +| 6 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Add a feature-gate table | +| 7 | Project Documentation | Information architecture | 2 - High | `add-a-user-facing-troubleshooting-page.md` | (standalone issue) | +| 8 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add a landing page to each of the Compute, Network, and Storage sections | +| 9 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Rename API-centric page titles to user goals | +| 10 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Group legacy workload mechanisms under a Legacy heading | +| 11 | Project Documentation | Information architecture | 2 - High | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Remove or archive legacy installation content | +| 12 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add the Plugins page to the navigation and delete the duplicate page | +| 13 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Move Release Notes out of the middle of the main navigation | +| 14 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Add a Getting Started page after Architecture | +| 15 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | +| 16 | Project Documentation | New user content | 1 - Urgent | `U-create-a-new-user-getting-started-path.md` | End the Installation page with a Next steps section | +| 17 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | +| 18 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Expand the virtctl page and rename it "Installing virtctl" | +| 19 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | +| 20 | Project Documentation | New user content | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Enable code copy and search features in the theme | +| 21 | Project Documentation | New user content | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Convert code blocks on the new-user path
Convert code blocks on the longest reference pages | +| 22 | Project Documentation | New user content | 3 - Backlog | `U-create-a-new-user-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | +| 23 | Project Documentation | New user content | 1 - Urgent | `U-create-a-new-user-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Document the content versioning model | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Publish versioned documentation with a version selector | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Standardize the feature-state admonition | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Document the release-notes update process | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Enable code copy and search features in the theme | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Add a localization statement | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Ask about a site-wide search | +| 31 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Expand CONTRIBUTING.md into a full documentation contributor guide | +| 32 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | +| 33 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Write a documentation style guide | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a pull request template | +| 35 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | +| 36 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | +| 38 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md`
`U-remove-legacy-branch-names-and-minimizing-language.md` | Reword minimizing language on the five pages with the most occurrences
Reword minimizing language across the remaining pages | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Write a documentation style guide | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md` | Add an automated check for minimizing language | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | `U-remove-legacy-branch-names-and-minimizing-language.md` | Update legacy branch-name links and the Presets example | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | `U-remove-legacy-branch-names-and-minimizing-language.md` | Update legacy branch-name links and the Presets example | +| 44 | Project Documentation | Inclusive language | 2 - High | `U-remove-legacy-branch-names-and-minimizing-language.md` | Prefer "cancel" over "abort" in Live Migration prose | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md` | Use tagged or permalink URLs for upstream project links | +| 46 | Contributor documentation | Communication methods documented | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Add repository and social links to every page | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Standardize on the `good first issue` label | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Seed and maintain a pool of beginner issues | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Triage the open issue backlog | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Standardize on the `good first issue` label | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Triage the open issue backlog | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Seed and maintain a pool of beginner issues | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Publish a documentation triage cadence and give documentation a SIG home | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Making your first documentation change" walkthrough | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Contributing to the code" subsection and document mentoring | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Contributing to the code" subsection and document mentoring | +| 63 | Contributor documentation | Project governance documentation | 2 - High | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add a Governance section to the Community page | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Explain how the project is run on the Contributing page | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Explain how the project is run on the Contributing page | +| 66 | Contributor documentation | Project governance documentation | 2 - High | — | Not an issue — asks maintainers to audit SIG charters and `sigs.yaml` in `kubevirt/community`; a governance action outside the documentation scope. | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Document where documentation lives | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Move user-facing content out of kubevirt/kubevirt/docs | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Triage the CDI documentation the guide links to | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Record the repository and toolchain decisions | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Give the API reference a visible home in the user guide | +| 72 | Website & Infrastructure | Website requirements | 2 - High | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md` | (standalone issue) | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add the © symbol and the missing root repository files | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Point vendor logos at KubeVirt-specific pages | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add the © symbol and the missing root repository files | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Fix header and link contrast and align the brand color | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Replace the ASCII architecture diagram with an accessible diagram | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Convert code blocks on the new-user path | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Verify wide tables on mobile and add table captions | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Split Disks and Volumes by volume type
Split Interfaces and Networks and Live Migration
Split Release Notes by minor release | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Set the logo alt text and remove unused configuration and assets
Verify wide tables on mobile and add table captions | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Add an accessibility check to CI | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Publish a short brand reference | +| 86 | Website & Infrastructure | Branding and design | 2 - High | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Fix header and link contrast and align the brand color | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Add repository and social links to every page | +| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | — | Not an issue — optional logo-variant preference with minimal reader impact. | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Set the logo alt text and remove unused configuration and assets | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Set the logo alt text and remove unused configuration and assets | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Link the existing CNCF case studies from the landing page | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Show adopter use cases on the logo wall | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Create an adopters page | +| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | — | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add blog categories beyond news and uncategorized | +| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | — | Not an issue — a publishing-cadence commitment for the blog is a process decision, not a documentation change. | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | Enable analytics on the user guide | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Load analytics only in production (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Make preview builds reproducible and non-indexable (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Fix robots.txt, gate analytics to production, and block indexing of previews | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Make preview builds reproducible and non-indexable | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Index non-blog pages in site search and cross-link the two searches | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Site infrastructure section to the README | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | Set up a recurring 404 report and feed it into the redirects map | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Site infrastructure section to the README | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Publish a documentation triage cadence and give documentation a SIG home | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | +| 110 | Website & Infrastructure | Maintenance planning | 2 - High | — | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by the beginner issue backlog issue. | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Record the repository and toolchain decisions | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Make preview builds reproducible and non-indexable | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Strict-Transport-Security header or record the gap | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | + +## Priority adjustments + +Umbrella labels follow the highest-priority sub-issue, with these exceptions: + +| Recommendation | CSV priority | Issue label | Reason | +|---|---|---|---| +| 42, 43 (legacy `master` links and node-name example) | 1 - Urgent | high (`U-remove-legacy-branch-names-and-minimizing-language.md`) | Two small fixes in an umbrella whose remaining work is backlog-priority prose cleanup. They are the first sub-issue so they can be done immediately; split them out if the umbrella's label matters. | +| 81, 83 (mobile table check and captions) | 1 - Urgent | high (`U-improve-accessibility-mobile-usability-and-code-blocks.md`) | The logo alt-text half of 83 is in the urgent configuration issue. The remaining verification and caption work is small and sits alongside the other accessibility fixes. | +| 8, 9, 10 (landing pages, title renames, Legacy grouping) | 3 - Backlog | urgent (`U-fix-navigation-gaps-and-reorganize-information-architecture.md`) | Bundled with urgent navigation fixes because they touch the same `.nav.yml` files; the sub-issues can be deferred independently. | +| 22 (Quickstarts introduction) | 3 - Backlog | urgent (`U-create-a-new-user-getting-started-path.md`) | Combined with the urgent Welcome "Start here" link because both are one-paragraph edits to entry pages. | +| 53, 54, 55 (`help wanted` guidance, `lifecycle/frozen`, issue checklist) | 3 - Backlog | urgent (`U-document-community-channels-and-maintain-a-beginner-issue-backlog.md`) | Bundled into the label-standardization, triage, and seeding sub-issues they naturally belong to. | +| 74, 85, 95, 104 (vendor logos, brand reference, blog categories, site search) | 3 - Backlog | urgent (`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md`) | Grouped with the urgent website compliance fixes because all land in `kubevirt/kubevirt.github.io`; these are the last four sub-issues and can be deferred. | +| 27, 29 (release-notes process, localization) | 3 - Backlog | high (`U-document-the-versioning-model-and-publish-versioned-documentation.md`) | Both are short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| 106 (404 report) | 3 - Backlog | high (`U-enable-analytics-on-the-user-guide-and-fix-broken-links.md`) | Depends on the analytics sub-issues in the same umbrella. | +| 68, 69, 109, 114 (content audits, maintainer ladder, OWNERS_ALIASES) | 3 - Backlog | high (`U-document-site-infrastructure-ownership-and-documentation-boundaries.md`) | Grouped with the ownership and boundary documentation they implement. | + +## Notes for the writer + +- `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` describes changes to `kubevirt/kubevirt.github.io`. Its `repo` is set to the user guide per the instructions; change it to `https://github.com/kubevirt/kubevirt.github.io/issues` if the upload should target the website repository directly. +- Recommendations 75, 77, 100, and 101 each have a user-guide half and a website half and appear in two files. + + +## Counts + +- Recommendations: 114 +- Covered by an issue: 109 +- Not an issue: 5 +- Issue files: 14 (12 umbrella, 2 standalone) +- Sub-issues: 77 diff --git a/analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md b/analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md new file mode 100644 index 00000000..689b5996 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md @@ -0,0 +1,42 @@ +--- +title: Apply low-effort mkdocs.yml and build configuration improvements +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +Several one-line configuration changes in `mkdocs.yml` and `netlify.toml` would noticeably improve the guide: copyable code blocks, better search, social links in the header and footer, correct logo alt text, reproducible builds, and no indexing of preview deploys. None requires content changes. Each sub-issue is a single pull request of configuration edits plus a local build (`mkdocs serve`) to confirm the result. + +## Sub-issues + +### Enable code copy and search features in the theme + +Under `theme.features` in `mkdocs.yml`, add: + +- `content.code.copy`, which adds a copy button to every code block. +- `search.suggest`, `search.highlight`, and `search.share`, which improve search usability. + +Done when: a copy button appears on code blocks and search shows suggestions and highlights terms. + +### Add repository and social links to every page + +In `mkdocs.yml`, set `repo_url` to the `kubevirt/user-guide` repository and add an `extra.social` block with the project's GitHub, Slack, mailing list, and `kubevirt.io` links. These appear in the header and footer on every page instead of only in the "Getting help" list on the Welcome page. + +Done when: the header shows the repository link and the footer shows the social icons. + +### Set the logo alt text and remove unused configuration and assets + +- Set the logo alt text to "KubeVirt" by adding `extra.homepage` or a custom `overrides/partials/logo.html`. +- Remove the unsupported top-level `site_favicon` key from `mkdocs.yml`; MkDocs ignores it and the active favicon is already set under `theme.favicon`. +- Remove the unused legacy assets `asciibinder-logo-horizontal.png`, `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. + +Done when: the logo has alt text, `mkdocs build --strict` reports no unknown keys, and `docs/assets` contains only current brand assets. + +### Make preview builds reproducible and non-indexable + +- Pin the MkDocs package versions in `netlify.toml`, or add a `requirements.txt`, so preview builds match the Prow image. +- Remove the obsolete `sed` line in `netlify.toml` that rewrites `site_url: https://kubevirt.io/docs`; `mkdocs.yml` already sets `site_url` to `https://kubevirt.io/user-guide`. +- Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file or a `[context.deploy-preview]` and `[context.branch-deploy]` section in `netlify.toml`, rather than relying on Netlify defaults. + +Done when: a deploy preview builds with pinned versions and returns the `noindex` header. diff --git a/analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md b/analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md new file mode 100644 index 00000000..fdd1d217 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md @@ -0,0 +1,85 @@ +--- +title: Build a documentation contributor guide and review process +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +`CONTRIBUTING.md` is a pointer, the Contributing page lists links without explaining them, and there is no style guide, pull request template, or named documentation maintainer. New contributors cannot tell how to make a change, who reviews it, or what "done" looks like, and twelve pull requests sit open. + +The sub-issues below turn `CONTRIBUTING.md` and `docs/contributing.md` into a complete contributor guide, add the supporting files that make reviews predictable, and route reviews to the right people. The Thanos "How to contribute to docs" page and the NATS `MAINTAINERS` file are good models. + +## Sub-issues + +### Expand CONTRIBUTING.md into a full documentation contributor guide + +Rewrite `CONTRIBUTING.md` to cover the full lifecycle: how to propose a change, how to build and test locally (move the build steps from the README here), what happens after opening a pull request (labels, `/lgtm`, `/approve`, expected turnaround), when to add a redirect to `mkdocs.yml`, and when a change needs a cherry-pick to a `release-vX.Y-stable` branch. Summarize the key points on the Contributing page and link to the full guide. + +Done when: a first-time contributor can go from clone to merged PR using only this file. + +### Add a "Making your first documentation change" walkthrough + +Add a section to `docs/contributing.md` that walks through the mechanics end to end: find or file an issue, comment to claim it, fork and branch, edit under `docs/` and update `.nav.yml`, run `make check_spelling` and `make check_links`, sign off with `git commit -s`, open the pull request, and what to expect from Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. + +Done when: every step names the command or UI action to take. + +### Add "Where to ask for help" and direct links to beginner issues + +On `docs/contributing.md`, and repeated in `CONTRIBUTING.md`: + +- Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and `#virtualization` for usage questions, and link the Slack invitation page. +- State that the weekly community meeting includes newcomer introductions, with the day, time, and meeting link. +- Identify the documentation approvers or a docs contact. +- Replace the generic "look for good-first-issue" advice with direct links to the filtered issue list for each repository. +- Link the `kubevirt/community` resources newcomers need: the SIG list, the help-wanted guide, the community meeting document, and the `MAINTAINERS` file. + +Done when: a newcomer can find a person to ask and an issue to pick up from this page. + +### Explain how the project is run on the Contributing page + +Above the "Important community resources" list on `docs/contributing.md`, add a short "How the project is run" paragraph that names the maintainer group, explains that work is organized in SIGs, and states that decisions default to lazy consensus. Give each link in the resource list a one-sentence description of what the reader will find. + +Done when: a newcomer understands the structure before following any link. + +### Add a "Contributing to the code" subsection and document mentoring + +Add a subsection to `docs/contributing.md` that summarizes the `kubevirt/kubevirt` path in three or four steps: read its `CONTRIBUTING.md`, follow `docs/getting-started.md` to build and run a local cluster, pick an issue, open a draft PR. + +Ask the community whether a mentoring or buddy arrangement exists for first-time contributors. The help-wanted guide promises "extra assistance" on `good first issue` items; state how to request it. + +Done when: code-minded newcomers see a clear next step and know how to ask for help. + +### Write a documentation style guide + +Add a short style guide, linked from `CONTRIBUTING.md` and the Contributing page, that covers: + +- Page structure: title, short concept, feature-state banner, procedure, related links. +- The standard feature-state admonition. +- Code block conventions: fenced blocks, no `$` prompts, output in a separate block. +- Kubernetes object capitalization (VirtualMachine, VirtualMachineInstance) and file naming. +- A rule that discourages "simple", "simply", "easy", "easily", "just", and "obviously", with a one-line explanation of why. + +Done when: a reviewer can point to the guide for each common review comment. + +### Add a pull request template + +Add `.github/PULL_REQUEST_TEMPLATE.md` with a checklist: `.nav.yml` updated for new pages, redirect added for moved pages, spelling and link checks run, feature-state banner present, and the related `kubevirt/kubevirt` PR or VEP linked. + +Done when: new pull requests open with the checklist. + +### State the code-freeze requirement and a stale-PR policy, and triage open pull requests + +- On the Contributing page, state that the VEP checklist requires the docs PR to be merged by code freeze. +- Add a stale-PR policy to `CONTRIBUTING.md` so contributors know what to expect. +- Triage the currently open pull requests: merge or close the oldest, and leave a comment on each remaining one stating what it needs. + +Done when: the policy is published and every open PR has a current status comment. + +### Name maintainers and route reviews to subject-matter experts + +- Add a `MAINTAINERS.md`, or a "Maintainers" section on the Contributing page, that names the user guide approvers and the person or group responsible for the release-notes script, and how to reach them. +- Add per-directory `OWNERS` files (`docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS`) that reference the existing `sig-network-*`, `sig-storage-*`, and `sig-compute-*` aliases, keeping the root approvers for site-wide changes. +- Ask the maintainers to consider a documentation-focused reviewer role or SIG Docs alias so writers who are not code approvers can share the review load. + +Done when: a pull request touching `docs/storage/` requests review from the storage alias. diff --git a/analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md b/analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md new file mode 100644 index 00000000..8c0e63b9 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md @@ -0,0 +1,70 @@ +--- +title: Create a new-user Getting Started path from installation to a running VirtualMachine +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +A new user who arrives at the user guide cannot follow one path from "I have a cluster" to "I have a running VM." The Installation page buries the four-command install under platform-specific material, the `virtctl` page covers only one binary, Basic Use centers on VirtualMachineInstance rather than VirtualMachine, Lifecycle references a `vmi.yaml` that is never defined, and nothing on the Welcome page tells a newcomer where to start. + +The sub-issues below add a single Getting Started page and reshape the pages it links to so each one hands the reader to the next. Complete the sub-issues in order where possible; the later ones link to pages created by the earlier ones. + +## Sub-issues + +### Add a Getting Started page after Architecture + +Create `docs/getting_started.md` and add it to `docs/.nav.yml` immediately after Architecture. On one page, walk a reader from a working cluster to a running VM: + +1. Install KubeVirt with the four `kubectl` commands from the Installation page. +2. Install `virtctl`. +3. Create a VirtualMachine from a provided minimal manifest or `virtctl create vm`. +4. Start it, connect with `virtctl console`, and stop it. + +Link to the detailed page at each step rather than repeating its content. Consider folding the current Quickstarts page into this page as a "Try it in a sandbox" section. + +Done when: a reader can complete the page in under 30 minutes on a fresh cluster and every step links to the page that explains it. + +### Point newcomers at the Getting Started page from Welcome and Quickstarts + +On the Welcome page (`docs/index.md`), add a one-line "New to KubeVirt? Start here" link at the top that points to the Getting Started page. + +On the Quickstarts page (`docs/quickstarts.md`), add 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 will have at the end. Add a closing link to the Getting Started page. + +Done when: both pages link to Getting Started and the Quickstarts page states its prerequisites. + +### Rewrite Basic Use as "Your first VirtualMachine" and fix the Lifecycle manifest reference + +Rewrite `docs/user_workloads/basic_use.md` into a short page that presents 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. +- The `kubectl apply`, `virtctl start`, `virtctl console`, and `virtctl stop` commands. +- Explicit links to the next pages (Creating VirtualMachines, Accessing Virtual Machines, Lifecycle). + +Update `docs/user_workloads/lifecycle.md` to reference that `vm.yaml` manifest instead of the undefined `vmi.yaml`. + +Done when: Basic Use and Lifecycle use the same manifest and a reader can run both pages end to end. + +### Restructure the Installation page so the core procedure comes first + +Reorder `docs/cluster_admin/installation.md` so the first screen covers Requirements, the four-command operator install, verification, and the emulation fallback. Move the following below a "Platform-specific and advanced installation" heading, or onto separate pages: AppArmor, kernel and user-land compatibility, SELinux, OKD, k3OS, daily developer builds, deploying from source, network plugins, and node placement. + +Remove, or move to a footnote, the historical notes about behavior before v0.20.0 and v0.34.2. Ask the maintainers whether any supported upgrade path still requires them. + +Done when: the standard install is complete before the first platform-specific heading. + +### End the Installation page with a Next steps section + +Add a "Next steps" section to the end of `docs/cluster_admin/installation.md` that links to Installing virtctl, Creating VirtualMachines by using virtctl, and Accessing Virtual Machines. + +Done when: the Installation page no longer ends on an advanced topic. + +### Expand the virtctl page to cover all client binaries and rename it "Installing virtctl" + +Expand `docs/user_workloads/virtctl_client_tool.md` to cover every published client binary. Use the Material theme's content tabs for Linux, macOS, and Windows on both amd64 and arm64, and include the `chmod +x` and `PATH` steps. Rename the page title to "Installing virtctl". Either move the page next to Installation in the navigation or link to it from Installation's Next steps. + +Done when: a user on any supported platform can install `virtctl` from this page alone. + +## Related + +The virtctl command reference and the Troubleshooting page are tracked separately; link to them from Getting Started when they exist. diff --git a/analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md b/analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md new file mode 100644 index 00000000..4486945a --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md @@ -0,0 +1,45 @@ +--- +title: Document community channels in the guide and maintain a beginner-friendly issue backlog +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +Readers who stay inside the user guide see only a raw Slack URL on the Welcome page; the channels, mailing list, and community meetings are documented on `kubevirt.io/community` but not in the guide. On the contributor side, the repository uses two spellings of the good-first-issue label, so beginner issues do not appear in GitHub's "Contribute" tab, and unlabeled issues reach `lifecycle/rotten` and close without triage. + +The sub-issues below bring the community information into the guide and set up the labels, triage habits, and cadence that keep a small pool of beginner issues available. Documentation also needs a formal home in the community SIG list so newcomers know where to volunteer. + +## Sub-issues + +### Add a Community and communication page to the guide + +Add a page, or a section on the Contributing page, that consolidates the Slack channels, the `kubevirt-dev` mailing list, community meetings, and social accounts in one place. Give each channel a one-line description of its purpose: `#virtualization` for usage questions, `#kubevirt-dev` for contributor discussion, the mailing list for announcements and longer threads. State the meeting cadence and times and include the public calendar link (`kubevirt@cncf.io`). Keep the content consistent with `kubevirt.io/community`. + +On the Welcome page, replace the raw Slack URL with the channel name and a link to the Kubernetes Slack invitation page. Add a short "Community and adoption" block to `docs/index.md` that links to the `kubevirt.io` blog, videos, Summit, adopters page, and Slack. On `docs/contributing.md`, where readers are invited to submit case studies, link the existing adopters list and CNCF case studies so contributors can see the format they are being asked to follow. + +Done when: a reader can find every channel and the meeting schedule without leaving the guide. + +### Standardize on the `good first issue` label + +Standardize on the GitHub-native `good first issue` label (spaced) and retire or alias the hyphenated `good-first-issue`, so beginner issues appear in GitHub's "Contribute" tab and discovery tooling. Relabel existing issues and update the reference on the Contributing page to match. Reference both `good first issue` and `help wanted` on the Contributing page and explain the difference: `help wanted` marks slightly larger but still approachable tasks. + +Done when: only one spelling of the label is in use and the Contributing page explains both labels. + +### Triage the open issue backlog + +Apply `kind/*` and `sig/documentation` labels to unlabeled open issues, and apply `triage/accepted` to issues that are ready to be worked on. Apply `lifecycle/frozen` to still-relevant enhancements and documentation requests so they do not reach `lifecycle/rotten` and close for inactivity alone. + +Done when: every open issue has a `kind/*` label and a triage state. + +### Seed and maintain a pool of beginner issues + +Identify documentation gaps, typos, and small feature-doc updates and file them as `good first issue`, aiming for five to ten open at any time. Add a short "good first issue" checklist to the issue templates (affected page, expected outcome, pointers to relevant docs) so each beginner issue is self-contained. + +Done when: at least five `good first issue` items are open and each follows the checklist. + +### Publish a documentation triage cadence and give documentation a SIG home + +Publish a lightweight triage cadence, for example a periodic documentation-issue triage during a SIG or community meeting, so labeling, acceptance, and staleness decisions stay consistent. Populate the `sig/documentation` entry in the community `sig-list.md` with chairs, a meeting cadence or async channel, and a charter that covers both the user guide and the website. + +Done when: the cadence is written down on the Contributing page and `sig-list.md` has a complete documentation entry. diff --git a/analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md b/analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md new file mode 100644 index 00000000..350997ab --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md @@ -0,0 +1,55 @@ +--- +title: Document site infrastructure ownership and the boundary between documentation sources +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +Nobody can tell from the repositories who administers the Netlify site, DNS, GitHub Pages, analytics, or the Prow jobs, or how to become a user guide approver. User-facing content is also spread across three places: this guide, `kubevirt/kubevirt/docs`, and the CDI `doc/` directory, with no statement of which content belongs where. + +The sub-issues below write down infrastructure ownership and the maintainer ladder so the sites survive maintainer turnover, and define and enforce a content boundary so users find documentation in one place. + +## Sub-issues + +### Add a Site infrastructure section to the README + +Add a "Site infrastructure" section to the README of `kubevirt/user-guide` (and propose the same for `kubevirt/kubevirt.github.io`, or a page in `kubevirt/community`) that lists who administers the Netlify site, GitHub Pages and custom-domain settings, DNS for `kubevirt.io`, the analytics and Search Console accounts, and the Prow job definitions in `kubevirt/project-infra`, and how a maintainer requests access or a 404 report. + +Done when: every piece of infrastructure names an owner and an access path. + +### Publish a maintainer ladder and keep OWNERS_ALIASES current + +In the README, describe how a contributor becomes a reviewer and then an approver (for example, a number of merged docs PRs and a nomination), mirroring the process in `kubevirt/community` for code SIGs. Review `OWNERS_ALIASES` and add dated emeritus entries for inactive approvers, as the website repository already does. + +Done when: the ladder is published and `OWNERS_ALIASES` lists only active approvers plus dated emeritus entries. + +### Add a Strict-Transport-Security header or record the gap + +GitHub Pages does not let you set response headers directly. Either enable HSTS through the DNS or CDN provider in front of `kubevirt.io`, or record the limitation in the Site infrastructure section so it is a known gap. For the user guide on Netlify, add the header in `netlify.toml`. + +Done when: `curl -I https://kubevirt.io/user-guide/` returns `Strict-Transport-Security`, and the main site's status is recorded. + +### Document where documentation lives + +Add a short "Where documentation lives" section to the README of `kubevirt/user-guide`, and propose the same text for `kubevirt/kubevirt.github.io` and `kubevirt/kubevirt`, stating that user and operator documentation belongs in the user guide, marketing, blog, and community content belongs on the website, and `kubevirt/kubevirt/docs` is for design and developer notes only. Link to it from `docs/contributing.md`. + +Done when: all three repositories state the same boundary. + +### Record the repository and toolchain decisions + +Decide whether the website and user guide should share a repository, and record the decision in both READMEs with the reason (for example, different generators, maintainers, and audiences). Open a tracking issue to evaluate converging the two toolchains on Material for MkDocs or another generator with a supported theme, so a single skill set covers both sites, even if the migration is deferred. + +Done when: both decisions are written down with an owner and a revisit date. + +### Move user-facing content out of kubevirt/kubevirt/docs + +Audit `kubevirt/kubevirt/docs` for user-facing content, starting with the files the user guide already links to (`getting-started.md`, `architecture.md`, `cloud-init.md`). Move the user-facing portions into the guide and replace the originals with a one-line pointer so search results and old links still resolve. + +Done when: the guide no longer links to `kubevirt/kubevirt/docs` for user-facing content. + +### Triage the CDI documentation the guide links to + +Six storage pages link to the CDI `doc/` directory. Either move those pages into the guide's `storage/` section, or add a "CDI reference documentation" page in the guide that explains why the rest remains in the CDI repository and links to it. + +Done when: every CDI link from the guide goes through a page that explains the boundary. diff --git a/analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md b/analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md new file mode 100644 index 00000000..110047f4 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md @@ -0,0 +1,43 @@ +--- +title: Document the versioning model and publish versioned documentation +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but nothing explains what they are for, which one is published, or when a change on `main` needs a cherry-pick. Only one version of the guide is published, so users on an older KubeVirt release read documentation for features they do not have. The release-notes regeneration step and the project's localization position are also undocumented. + +The sub-issues below record the versioning workflow, publish versioned documentation with a version selector, and close the remaining documentation-process gaps. Confirm the intended workflow with the maintainers first; the `-devel` branches exist for 1.7 and 1.8 but not 1.9, which suggests the process has drifted. + +## Sub-issues + +### Document the content versioning model + +In `CONTRIBUTING.md`, and summarized on the Contributing page, state what the `release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are cut relative to a KubeVirt release, which branch is published, and how a contributor decides whether a change on `main` needs a cherry-pick. Confirm the intended workflow with the maintainers before writing. + +Done when: a contributor can decide from the text alone whether to cherry-pick. + +### Publish versioned documentation with a version selector + +Publish versioned documentation using either `mike` with the theme's `extra.version.provider: mike` setting, or a build per release branch published under a `/vX.Y/` path. Publish at least the supported N, N-1, and N-2 minors alongside `latest`. Start by prototyping the build locally and documenting the release-time steps; the Netlify and Prow changes can follow in a second pull request. + +Done when: the published guide shows a version selector with at least three versions. + +### Document the release-notes update process + +Record when `update_changelog.sh` is run, by whom, and how the result is reviewed, so the Release Notes page continues to be regenerated after maintainer turnover. Add this to `CONTRIBUTING.md` next to the versioning model. + +Done when: the process is written down and names a responsible role. + +### Add a localization statement + +Add a short "Localization" statement to `CONTRIBUTING.md` that records the project's current position: English only, translations not currently accepted, or translations welcome via a stated process. If translations are anticipated within the next few releases, move content to `docs/en/` now and configure the `mkdocs-static-i18n` plugin so the redirects and `.nav.yml` files only need to change once. + +Done when: a prospective translator knows whether and how to contribute. + +### Ask about a site-wide search across the user guide, API reference, and quickstarts + +Ask the KubeVirt website maintainers whether the API reference and quickstarts can be indexed by the same search as the user guide, for example by moving the user guide search to a site-wide index. Record the decision in this issue and, if agreed, open a follow-up with the implementation plan. + +Done when: a decision is recorded. diff --git a/analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md b/analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md new file mode 100644 index 00000000..47557d93 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md @@ -0,0 +1,50 @@ +--- +title: Document v1.9 features and add feature-gate and virtctl reference pages +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +Several features shipped in KubeVirt v1.9 appear only in the release notes, so users cannot find how to use them. The guide also lacks two reference pages that readers expect: a list of feature gates with their stage and version, and a list of `virtctl` subcommands. Feature pages that do state a stage use an informal `FEATURE STATE:` block whose format varies. + +The sub-issues below add the missing feature documentation, create the two reference pages, and standardize the feature-state banner so future pages follow one pattern. + +## Sub-issues + +### Document the VirtualMachineBackup API + +Add a page under `docs/storage/` that explains the `VirtualMachineBackup` API introduced in v1.9: what it backs up, the required feature gate, a minimal manifest, how to check status, and how it relates to the snapshot and export features. Add it to `docs/storage/.nav.yml` and link it from the release notes entry. + +Done when: a user can create and verify a backup by following the page. + +### Document the CrossArchitectureVirtualization feature gate + +Add a section or page, under `docs/compute/` or `docs/cluster_admin/`, for the `CrossArchitectureVirtualization` feature gate: what it enables, the supported architecture combinations, how to enable it, and known limitations. Link it from the Arm64 pages where relevant. + +Done when: the gate is documented somewhere other than the release notes. + +### Document masquerade PortRanges and MigrationPolicy compression + +- In Interfaces and Networks (`docs/network/interfaces_and_networks.md`), add a subsection on masquerade `PortRanges` with a manifest example. +- In Migration Policies (`docs/cluster_admin/migration_policies.md`), add a subsection on MigrationPolicy compression with a manifest example and guidance on when to enable it. + +Done when: both features are documented on the page where users configure them. + +### Create a virtctl command reference + +Create a `virtctl` command reference page, or expand `docs/user_workloads/virtctl_client_tool.md` beyond installation, that lists each subcommand with a one-line description and a link to the feature page that explains it in context. Generate the subcommand list from `virtctl --help` for the current release so it is complete. + +Done when: every `virtctl` subcommand appears with a description and a link. + +### Add a feature-gate table to the feature gates page + +On Activating and Deactivating Feature Gates (`docs/cluster_admin/activating_feature_gates.md`), add a table that lists each feature gate, its stage (Alpha, Beta, GA, Deprecated), the version it was introduced or graduated, and a link to its documentation. Ask the maintainers whether this table can be generated from the `kubevirt/kubevirt` source to avoid drift; if so, document the generation step. + +Done when: every feature gate in the current release appears in the table. + +### Standardize the feature-state admonition and apply it to every feature page + +Define a standard feature-state admonition that states the version introduced and the current stage (Alpha, Beta, GA, Deprecated). Document its format in `CONTRIBUTING.md`. Replace the existing `FEATURE STATE:` blocks on the pages that have them and add the admonition to feature pages that have none. + +Done when: every feature page opens with the same admonition format. diff --git a/analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md b/analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md new file mode 100644 index 00000000..1ad2d7c3 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md @@ -0,0 +1,29 @@ +--- +title: Enable analytics on the user guide and use it to fix broken links +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +The user guide collects no analytics, so maintainers cannot see which pages are read, what users search for, or which URLs return 404. The main site has an Adobe Analytics tag, but it also fires on preview deploys, which pollutes the data. The sub-issues below add analytics to the guide, restrict it to production, and set up the one report that pays for itself: a list of 404 hits to feed the `redirects` map in `mkdocs.yml`. + +## Sub-issues + +### Enable analytics on the user guide + +Add an `extra.analytics` block to `mkdocs.yml`. The Material theme supports Google Analytics 4 natively; alternatively, add a custom `overrides/main.html` partial that loads the same Adobe Analytics tag the main site uses so both properties report to one place. Confirm with the website maintainers which property to use. + +Done when: page views from `kubevirt.io/user-guide` appear in the chosen analytics property. + +### Load analytics only in production + +Inject the analytics snippet only when the Netlify `CONTEXT` variable equals `production`, for example by templating it in the `netlify.toml` build command or by reading an environment variable in the override partial. + +Done when: a deploy preview loads no analytics script. + +### Set up a recurring 404 report and feed it into the redirects map + +Once analytics are live, create a saved report filtered on the not-found page title, review it on a regular cadence, and add missing entries to the `redirects` plugin map in `mkdocs.yml`. Document the cadence and the report location in the README's site infrastructure section. + +Done when: the report exists and the first batch of redirects from it is merged. diff --git a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md new file mode 100644 index 00000000..e6534822 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md @@ -0,0 +1,78 @@ +--- +title: Fix kubevirt.io compliance, SEO, and adopter content gaps +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +The documentation analysis covered the main `kubevirt.io` website as well as the user guide, and found gaps on the website that affect documentation users: the copyright line is missing its © symbol, `robots.txt` points at the wrong sitemap and omits the user guide's, the site search indexes only blog posts, there is no root `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md`, two published CNCF case studies are not linked anywhere, and the adopter use cases in `ADOPTERS.md` never reach the site. + +All changes in this issue land in the `kubevirt/kubevirt.github.io` repository. The issue is filed here so the documentation work is tracked in one place; transfer it if the maintainers prefer. + +## Sub-issues + +### Add the © symbol and the missing root repository files + +- In `_includes/footer.html`, change the copyright line to read "Copyright © KubeVirt a Series of LF Projects, LLC". +- Add a root `CONTRIBUTING.md` that points to the existing contributing content in the README and to the user guide's Contributing page. +- Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of conduct. +- Add a note to the README naming the file to edit when the CNCF maturity statement changes. + +Done when: the footer shows ©, and both files exist at the repository root. + +### Fix robots.txt, gate analytics to production, and block indexing of previews + +- In `robots.txt`, correct the sitemap URL to `https://kubevirt.io/sitemap.xml` and add a second `Sitemap:` line for `https://kubevirt.io/user-guide/sitemap.xml`. +- In `_includes/head.html`, wrap the `dpal.js` Adobe Analytics include in a check on `jekyll.environment == "production"`, and set `JEKYLL_ENV=production` only in the Netlify production context. +- Emit `X-Robots-Tag: noindex` for deploy previews and branch deploys from a `_headers` file or `netlify.toml` context section. + +Done when: `robots.txt` lists both sitemaps, previews send no analytics, and previews return the `noindex` header. + +### Link the existing CNCF case studies from the landing page + +Add a "Case Studies" block beneath the End Users logo wall on the landing page that links the two published CNCF case studies (NTT Docomo Business and Swisscom). The content already exists; this is a quick win. + +Done when: both case studies are reachable from the landing page. + +### Show adopter use cases on the logo wall + +Extend `adopters.py` and `_data/adopters.yml` to carry the "Use-Case" text from `ADOPTERS.md`, and show it as a tooltip or an expandable card on each logo. This turns the logo wall into short, attributed testimonials at no authoring cost. + +Done when: hovering or expanding a logo shows that adopter's use case. + +### Create an adopters page + +Create a `/adopters/` or `/case-studies/` page that renders the full adopters table (type, name, since, use case) and links to the CNCF case studies, so evaluators have a single place for adoption evidence. Add it to `_data/site_nav_pages.yml`. + +Done when: the page is in the site navigation and lists every adopter. + +### Add a Governance section to the Community page + +Add a "Governance" section to the Community page that states in two or three sentences how KubeVirt is governed (CNCF incubating project, maintainer group, SIGs and working groups, lazy consensus with maintainer votes) and links `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in `kubevirt/community`. + +Done when: a visitor can find the governance documents from the Community page. + +### Index non-blog pages in site search and cross-link the two searches + +Extend the lunr index in `_layouts/search.html` to include `site.pages` in addition to `site.posts`, so non-blog pages are searchable. Add a link from the main site's search page to the user guide search, and from the user guide's search results to the main site's, so users can find documentation from either entry point. + +Done when: a search for "installation" on `kubevirt.io` returns the relevant page. + +### Add blog categories beyond news and uncategorized + +Add a category or tag scheme (for example release, feature, community, user story) and backfill recent posts, so the blog index can filter by type and adopter stories can be listed together. + +Done when: the blog index offers category filtering and recent posts are tagged. + +### Point vendor logos at KubeVirt-specific pages + +For each entry in `ADOPTERS.md` whose link is a corporate homepage, ask the vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, and update the link. Drop the logo from the Vendors section if no such page exists. + +Done when: every vendor logo links to a page that mentions KubeVirt. + +### Publish a short brand reference + +Publish a brand reference, in this repository or in `kubevirt/community`, that lists the canonical logo files (icon and horizontal wordmark), the hex values of the `$kv-color--green-*` scale, and the approved typefaces. Have `docs/stylesheets/extra.css` in the user guide cite that reference in a comment so the two sites stay aligned when the palette changes. + +Done when: both repositories point at the same brand reference. diff --git a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md new file mode 100644 index 00000000..8f9fe193 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md @@ -0,0 +1,64 @@ +--- +title: Fix navigation gaps and reorganize the user guide information architecture +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +Several pages are unreachable or misplaced in the navigation, and page titles in the Storage section describe APIs rather than what a reader accomplishes. The Plugins page is reachable only from the deprecated Hook Sidecar page, a byte-identical duplicate of the Windows virtio drivers page is unlisted, Release Notes sits in the middle of the main navigation, and the API reference has no home in the guide. + +The sub-issues below fix the gaps first and then make the structure read as a progression from concepts through administration, workloads, and infrastructure layers. Every subdirectory under `docs/` has a `.nav.yml` that controls page order; when a file name changes, add a redirect in `mkdocs.yml`. + +## Sub-issues + +### Add the Plugins page to the navigation and delete the duplicate Windows virtio drivers page + +Add `plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is discoverable from somewhere other than the deprecated Hook Sidecar page. + +Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Add a redirect in `mkdocs.yml` if the old URL was ever published. + +Done when: Plugins appears in the Cluster Administration navigation and only one Windows virtio drivers page exists. + +### Move Release Notes out of the middle of the main navigation + +In `docs/.nav.yml`, move Release Notes to the end of the list or into a top-bar link, so the section list reads Welcome, Architecture, Getting Started, Cluster Administration, User Workloads, Compute, Network, Storage, then Contributing, Release Notes, and Virtualization Debugging. + +Done when: the main navigation reads as a progression without the Release Notes interruption. + +### Group legacy workload mechanisms under a Legacy heading + +In `docs/user_workloads/.nav.yml`, reorganize the Workloads sub-group so current mechanisms (instance types, VirtualMachine Templates, pools) come first and legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) sit under a clearly labeled "Legacy" heading or at the end. + +Done when: a reader sees the recommended mechanism before any deprecated one. + +### Add a landing page to each of the Compute, Network, and Storage sections + +Add a brief `index.md` landing page to `docs/compute/`, `docs/network/`, and `docs/storage/` that explains what the section covers and groups its pages by task. For example, Storage: provisioning disks, importing images, snapshots and backup, moving data between clusters. Add each landing page to its `.nav.yml`. + +Done when: each section opens on a page that orients the reader. + +### Rename API-centric page titles to user goals + +Rename page titles so they state what the reader accomplishes, for example: + +- "Clone API" to "Cloning VirtualMachines" +- "Export API" to "Exporting VirtualMachines and volumes" +- "Snapshot Restore API" to "Snapshotting and restoring VirtualMachines" +- "Migration Controller" to a title that states what the reader accomplishes with it + +Change titles in the page front matter and `.nav.yml` first. If you also rename files, add redirects in `mkdocs.yml`. + +Done when: no Storage page title ends in "API". + +### Give the API reference a visible home in the user guide + +Add a navigation entry or a short landing page that links to the API reference at `https://kubevirt.io/api-reference/`, so readers do not need to know it is published from a separate repository. + +Done when: a reader can reach the API reference from the guide's navigation. + +### Remove or archive legacy installation content + +Verify with the maintainers whether the OKD Service Catalog APB and k3OS installation paths on `docs/cluster_admin/installation.md` are still supported. Remove the paths that are not, and update the OpenShift 4.10 documentation links to a current version or a version-independent URL. + +Done when: the Installation page references only supported platforms and current links. diff --git a/analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md b/analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md new file mode 100644 index 00000000..c3faf3cf --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md @@ -0,0 +1,76 @@ +--- +title: Improve accessibility, mobile usability, and code block formatting +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +The guide's brand teal header and link color fall below the 4.5:1 contrast ratio that WCAG AA requires, the Architecture page's stack diagram is ASCII art that screen readers cannot interpret, wide tables may overflow on phones, and most code blocks use `$`-prefixed indented formatting that pastes badly and scrolls horizontally. Several pages exceed 500 lines, which makes them hard to navigate on any device. + +The sub-issues below fix the contrast and diagram problems, modernize the code blocks starting with the new-user path, split the longest pages, and add an automated check so the fixes stay fixed. Enable `content.code.copy` first (tracked in the configuration quick-wins issue) so the code block work shows its full benefit. + +## Sub-issues + +### Fix header and link contrast and align the brand color with the main site + +In `docs/stylesheets/extra.css`: + +- Darken `--md-primary-fg-color` to a teal that gives at least 4.5:1 against white, or keep the brand teal for decorative elements only and set the header and tab text to a dark foreground. +- Replace the `filter: brightness(80%)` link rule with explicit `--md-typeset-a-color` values per color scheme, each checked against 4.5:1. +- Replace the ad hoc `#0db2b6` primary with a value from the main site's documented `$kv-color--green-*` scale, for example `#00aab2`, or ask the website maintainers to add `#0db2b6` to the scale so both properties draw from one list. + +Verify both light and dark schemes with a contrast checker. + +Done when: header text and links meet 4.5:1 in both schemes and the primary color matches the main site's scale. + +### Replace the ASCII architecture diagram with an accessible diagram + +On the Architecture page (`docs/architecture.md`), replace the ASCII stack diagram with a Mermaid diagram (enable `pymdownx.superfences` custom fences for `mermaid` in `mkdocs.yml`) or an image with descriptive alt text. Add a one-paragraph prose description of the layers so screen reader and mobile users get the same information. + +Done when: the diagram renders on mobile and its content is available as text. + +### Verify wide tables on mobile and add table captions + +On a phone, check that the tables on `docs/cluster_admin/feature_gate_status_on_Arm64.md` and `docs/cluster_admin/device_status_on_Arm64.md` scroll horizontally rather than overflowing the page. If they overflow, remove the `display: table; width: max-content` override from `extra.css` or scope it to specific tables with `attr_list` classes. Add a short caption or introductory sentence above each wide status table stating what it shows. + +Done when: no table overflows on a 375 px viewport and each status table has a caption. + +### Convert code blocks on the new-user path to fenced blocks + +On Installation, Installing virtctl, Basic Use, and Lifecycle, convert `$`-prefixed indented code blocks to fenced `shell` blocks without prompt characters. Place example output in a separate block or a `title="Output"` annotation so commands paste cleanly. Break commands over 100 characters across lines with `\` continuations. + +Done when: every command on these pages can be copied and pasted without editing. + +### Convert code blocks on the longest reference pages + +Apply the same conversion to Disks and Volumes (`docs/storage/disks_and_volumes.md`), Export API (`docs/storage/export_api.md`), Interfaces and Networks (`docs/network/interfaces_and_networks.md`), and Live Migration (`docs/compute/live_migration.md`). + +Done when: these four pages contain no `$`-prefixed indented code blocks. + +### Split Disks and Volumes by volume type + +Split `docs/storage/disks_and_volumes.md` into an overview page plus one page per volume type or group of related types. Add the new pages to `docs/storage/.nav.yml` and redirects for any anchors that external pages link to. + +Done when: no resulting page exceeds about 500 lines and existing links resolve. + +### Split Interfaces and Networks and Live Migration + +- Split `docs/network/interfaces_and_networks.md` so binding methods and network attachment are separate pages. +- Move the migration strategies and network configuration sections of `docs/compute/live_migration.md` to sub-pages. + +Update the `.nav.yml` files and add redirects. + +Done when: each resulting page is under about 500 lines and existing links resolve. + +### Split Release Notes by minor release + +Split `docs/release_notes.md` into one page per minor release, or paginate it, and set the Release Notes navigation entry to open the newest release. Update `update_changelog.sh` so regeneration writes to the new structure. + +Done when: the newest release opens first and older releases load on separate pages. + +### Add an accessibility check to CI + +Add an accessibility check to the Makefile and the Prow pre-submit, for example `pa11y-ci` or Lighthouse run against the built site for a sample of pages, so contrast regressions are caught in pull requests. + +Done when: a pull request that lowers contrast below 4.5:1 fails the check. diff --git a/analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md b/analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md new file mode 100644 index 00000000..5f3f860d --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md @@ -0,0 +1,50 @@ +--- +title: Remove legacy branch names and minimizing language from the user guide +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Overview + +The guide links to the API reference at `/master/` paths fourteen times, uses `master` as an example node name, and relies on minimizing words such as "simply", "just", and "easily" that tell a struggling reader the task should have been easy. Fixing the links and example is quick. Rewording the prose is a page-by-page pass, and an automated check keeps new occurrences out. + +The style-guide rule that discourages minimizing language is tracked in the contributor guide issue. + +## Sub-issues + +### Update legacy branch-name links and the Presets example + +- Update the 14 links to `kubevirt.io/api-reference/master/...` to the `/main/` path, or to a specific version path such as `/v1.9.0/`. +- On the Presets page (`docs/user_workloads/presets.md`), replace the `kubevirt.io/nodeName: master` example with a neutral node name such as `node01`, or remove the example, since the page documents a deprecated feature. + +Done when: `grep -r "api-reference/master" docs/` returns nothing and the Presets page uses a neutral node name. + +### Reword minimizing language on the five pages with the most occurrences + +On Live Migration, Windows Virtio Drivers, Node Assignment, vsock, and Disks and Volumes, delete "simply", "just", "of course", and "obviously" where they add nothing, and replace "easy" or "easily" with a concrete statement of what the step requires. For example, change "can be easily cancelled" to "can be cancelled by deleting the migration object". + +Done when: none of the five pages contains the listed words in a minimizing sense. + +### Reword minimizing language across the remaining pages + +Apply the same pass to the rest of `docs/`. Use `grep -rniw "simply\|just\|easy\|easily\|obviously\|of course" docs/` to find occurrences and review each in context; some uses of "just" are legitimate. + +Done when: the grep returns only legitimate uses. + +### Prefer "cancel" over "abort" in Live Migration prose + +On the Live Migration page (`docs/compute/live_migration.md`), use "cancel" in the prose while continuing to show the `Abort Requested` and `Abort Status` field names as they appear in `kubectl` output. Ask the KubeVirt API maintainers whether those VirtualMachineInstanceMigration status fields are candidates for a "cancel" alias in a future API version, and record the answer in the issue. + +Done when: the prose says "cancel" and field names are shown in code formatting. + +### Add an automated check for minimizing language + +Add a check to the Makefile and the Prow pre-submit, alongside `make check_spelling`, that flags minimizing and non-recommended language in pull requests. Use Vale with the `write-good` style or a grep-based check. + +Done when: a pull request that adds "simply" fails the check. + +### Use tagged or permalink URLs for upstream project links + +Where the guide links to libvirt, cri-tools, vhost-md, or kubevirt-ansible files on a `master` branch, change the links to a tag or commit permalink so the branch name is not repeated in the guide and the link survives a default-branch rename. + +Done when: no outbound link in `docs/` includes `/master/`. diff --git a/analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md b/analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md new file mode 100644 index 00000000..61f8e20a --- /dev/null +++ b/analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md @@ -0,0 +1,35 @@ +--- +title: Add a user-facing Troubleshooting page +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + + + +## Description + +The guide has no page a user can turn to when something goes wrong. The Virtualization Debugging section is written for developers who need to attach `gdb` or `strace` to QEMU, and the troubleshooting notes that do exist for users are embedded in unrelated pages such as Accessing Virtual Machines and Memory Dump. + +Add a Troubleshooting page, separate from Virtualization Debugging, that lists common symptoms with likely causes and links to the fix. Start with these symptoms: + +- A VirtualMachineInstance stuck in `Scheduling` or `Pending`. +- A failed live migration. +- Console or VNC connection errors. +- Missing `qemu-guest-agent` data. + +For each symptom, give the `kubectl` or `virtctl` command that reveals the cause, the two or three most likely causes, and a link to the page that explains the fix. Move the troubleshooting notes from Accessing Virtual Machines and Memory Dump onto this page, or link to them from it. Add the page to `docs/.nav.yml` near Virtualization Debugging and link to it from the Getting Started page. + +## What you expected + +A user who hits a common failure can find a symptom-oriented page in the guide that leads them to the cause and the fix without reading the developer debugging section. + +## URL + +- https://kubevirt.io/user-guide/debug_virt_stack/debug/ (`docs/debug_virt_stack/debug.md`) +- https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ (`docs/user_workloads/accessing_virtual_machines.md`) +- https://kubevirt.io/user-guide/compute/memory_dump/ (`docs/compute/memory_dump.md`) + +## Additional context + +Keep the first version small. Four symptoms with accurate causes are more useful than a long list; the page can grow as users report more. diff --git a/analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md b/analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md new file mode 100644 index 00000000..b7b1545b --- /dev/null +++ b/analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md @@ -0,0 +1,32 @@ +--- +title: Bring the user guide footer and repository files into CNCF compliance +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + + + +## Description + +The CNCF website guidelines require every project property to show the Linux Foundation copyright line, the project's CNCF maturity statement, the CNCF logo, and a link to the LF Projects policies. The user guide footer shows none of these, and the repository has no root `CODE_OF_CONDUCT.md`. + +Make these changes: + +1. In `mkdocs.yml`, set `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"`. +2. Add `overrides/partials/copyright.html` (or a `footer.html` override) that appends "We are a Cloud Native Computing Foundation incubating project", the CNCF logo linked to `https://cncf.io`, and a link to `https://lfprojects.org/policies/` for trademark and terms. Match the wording and links used in the main website footer so the two properties read as one. +3. Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of conduct, so the file is present where the CNCF checklist expects it rather than only inherited from the organization default. +4. Add a note to the README naming the file to edit when the project's CNCF maturity status changes, so the footer statement does not go stale. + +## What you expected + +The user guide footer shows the same copyright, maturity statement, CNCF logo, and policy link as `kubevirt.io`, and the repository root contains a code of conduct. + +## URL + +- https://kubevirt.io/user-guide/ (footer on every page) +- `mkdocs.yml`, `overrides/`, `README.md` in the repository root + +## Additional context + +The theme's `custom_dir` must be set to `overrides` in `mkdocs.yml` for partial overrides to take effect; check whether it already is. From 2cec2794f2deb699659d086ee8ab357fc921f9dc Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 12 Oct 2026 18:40:59 -0700 Subject: [PATCH 02/31] shortened file names Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 266 +++++++++--------- ...cks.md => U-accessibility-improvements.md} | 0 ...rocess.md => U-build-contributor-guide.md} | 0 ...th.md => U-create-getting-started-path.md} | 0 ...og.md => U-document-community-channels.md} | 0 ...daries.md => U-document-site-ownership.md} | 0 ...ce-pages.md => U-document-v19-features.md} | 0 ...-broken-links.md => U-enable-analytics.md} | 0 ...tent-gaps.md => U-fix-kubevirt-io-gaps.md} | 0 ...chitecture.md => U-fix-navigation-gaps.md} | 0 ...age.md => U-inclusive-language-updates.md} | 0 ...provements.md => U-mkdocs-improvements.md} | 0 ...ntation.md => U-publish-versioned-docs.md} | 0 ...ng-page.md => add-troubleshooting-page.md} | 0 ...iance.md => fix-footer-cncf-compliance.md} | 0 15 files changed, 133 insertions(+), 133 deletions(-) rename analyses/2026/kubevirt/issues/{U-improve-accessibility-mobile-usability-and-code-blocks.md => U-accessibility-improvements.md} (100%) rename analyses/2026/kubevirt/issues/{U-build-a-documentation-contributor-guide-and-review-process.md => U-build-contributor-guide.md} (100%) rename analyses/2026/kubevirt/issues/{U-create-a-new-user-getting-started-path.md => U-create-getting-started-path.md} (100%) rename analyses/2026/kubevirt/issues/{U-document-community-channels-and-maintain-a-beginner-issue-backlog.md => U-document-community-channels.md} (100%) rename analyses/2026/kubevirt/issues/{U-document-site-infrastructure-ownership-and-documentation-boundaries.md => U-document-site-ownership.md} (100%) rename analyses/2026/kubevirt/issues/{U-document-v1-9-features-and-add-reference-pages.md => U-document-v19-features.md} (100%) rename analyses/2026/kubevirt/issues/{U-enable-analytics-on-the-user-guide-and-fix-broken-links.md => U-enable-analytics.md} (100%) rename analyses/2026/kubevirt/issues/{U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md => U-fix-kubevirt-io-gaps.md} (100%) rename analyses/2026/kubevirt/issues/{U-fix-navigation-gaps-and-reorganize-information-architecture.md => U-fix-navigation-gaps.md} (100%) rename analyses/2026/kubevirt/issues/{U-remove-legacy-branch-names-and-minimizing-language.md => U-inclusive-language-updates.md} (100%) rename analyses/2026/kubevirt/issues/{U-apply-low-effort-mkdocs-and-build-configuration-improvements.md => U-mkdocs-improvements.md} (100%) rename analyses/2026/kubevirt/issues/{U-document-the-versioning-model-and-publish-versioned-documentation.md => U-publish-versioned-docs.md} (100%) rename analyses/2026/kubevirt/issues/{add-a-user-facing-troubleshooting-page.md => add-troubleshooting-page.md} (100%) rename analyses/2026/kubevirt/issues/{bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md => fix-footer-cncf-compliance.md} (100%) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 61ddfc7f..8082e7f8 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -6,139 +6,139 @@ This report maps every recommendation in `.github/input/ai-ranked-recommendation | File | Label | Sub-issues | |---|---|---| -| `U-create-a-new-user-getting-started-path.md` | urgent | 6 | -| `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | urgent | 7 | -| `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | urgent | 4 | -| `U-document-v1-9-features-and-add-reference-pages.md` | high | 6 | -| `add-a-user-facing-troubleshooting-page.md` | high | standalone | -| `U-improve-accessibility-mobile-usability-and-code-blocks.md` | high | 9 | -| `U-remove-legacy-branch-names-and-minimizing-language.md` | high | 6 | -| `U-build-a-documentation-contributor-guide-and-review-process.md` | urgent | 9 | -| `U-document-the-versioning-model-and-publish-versioned-documentation.md` | high | 5 | -| `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | urgent | 5 | -| `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md` | urgent | standalone | -| `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | urgent | 10 | -| `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | high | 3 | -| `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | high | 7 | +| `U-create-getting-started-path.md` | urgent | 6 | +| `U-fix-navigation-gaps.md` | urgent | 7 | +| `U-mkdocs-improvements.md` | urgent | 4 | +| `U-document-v19-features.md` | high | 6 | +| `add-troubleshooting-page.md` | high | standalone | +| `U-accessibility-improvements.md` | high | 9 | +| `U-inclusive-language-updates.md` | high | 6 | +| `U-build-contributor-guide.md` | urgent | 9 | +| `U-publish-versioned-docs.md` | high | 5 | +| `U-document-community-channels.md` | urgent | 5 | +| `fix-footer-cncf-compliance.md` | urgent | standalone | +| `U-fix-kubevirt-io-gaps.md` | urgent | 10 | +| `U-enable-analytics.md` | high | 3 | +| `U-document-site-ownership.md` | high | 7 | ## Recommendation mapping | # | Section | Area | CSV priority | Issue file | Sub-issue | |---|---|---|---|---|---| -| 1 | Project Documentation | Information architecture | 2 - High | `U-create-a-new-user-getting-started-path.md` | Add a Getting Started page after Architecture | -| 2 | Project Documentation | Information architecture | 2 - High | `U-create-a-new-user-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | -| 3 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add the Plugins page to the navigation and delete the duplicate page | -| 4 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md`
`U-document-v1-9-features-and-add-reference-pages.md`
`U-document-v1-9-features-and-add-reference-pages.md` | Document the VirtualMachineBackup API
Document the CrossArchitectureVirtualization feature gate
Document masquerade PortRanges and MigrationPolicy compression | -| 5 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Create a virtctl command reference | -| 6 | Project Documentation | Information architecture | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Add a feature-gate table | -| 7 | Project Documentation | Information architecture | 2 - High | `add-a-user-facing-troubleshooting-page.md` | (standalone issue) | -| 8 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add a landing page to each of the Compute, Network, and Storage sections | -| 9 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Rename API-centric page titles to user goals | -| 10 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Group legacy workload mechanisms under a Legacy heading | -| 11 | Project Documentation | Information architecture | 2 - High | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Remove or archive legacy installation content | -| 12 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Add the Plugins page to the navigation and delete the duplicate page | -| 13 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Move Release Notes out of the middle of the main navigation | -| 14 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Add a Getting Started page after Architecture | -| 15 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | -| 16 | Project Documentation | New user content | 1 - Urgent | `U-create-a-new-user-getting-started-path.md` | End the Installation page with a Next steps section | -| 17 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | -| 18 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Expand the virtctl page and rename it "Installing virtctl" | -| 19 | Project Documentation | New user content | 2 - High | `U-create-a-new-user-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | -| 20 | Project Documentation | New user content | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Enable code copy and search features in the theme | -| 21 | Project Documentation | New user content | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Convert code blocks on the new-user path
Convert code blocks on the longest reference pages | -| 22 | Project Documentation | New user content | 3 - Backlog | `U-create-a-new-user-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | -| 23 | Project Documentation | New user content | 1 - Urgent | `U-create-a-new-user-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | -| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Document the content versioning model | -| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Publish versioned documentation with a version selector | -| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-v1-9-features-and-add-reference-pages.md` | Standardize the feature-state admonition | -| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Document the release-notes update process | -| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Enable code copy and search features in the theme | -| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Add a localization statement | -| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-the-versioning-model-and-publish-versioned-documentation.md` | Ask about a site-wide search | -| 31 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Expand CONTRIBUTING.md into a full documentation contributor guide | -| 32 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | -| 33 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Write a documentation style guide | -| 34 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a pull request template | -| 35 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | -| 36 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Name maintainers and route reviews to subject-matter experts | -| 37 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | -| 38 | Project Documentation | Content creation processes | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | -| 39 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md`
`U-remove-legacy-branch-names-and-minimizing-language.md` | Reword minimizing language on the five pages with the most occurrences
Reword minimizing language across the remaining pages | -| 40 | Project Documentation | Inclusive language | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Write a documentation style guide | -| 41 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md` | Add an automated check for minimizing language | -| 42 | Project Documentation | Inclusive language | 1 - Urgent | `U-remove-legacy-branch-names-and-minimizing-language.md` | Update legacy branch-name links and the Presets example | -| 43 | Project Documentation | Inclusive language | 1 - Urgent | `U-remove-legacy-branch-names-and-minimizing-language.md` | Update legacy branch-name links and the Presets example | -| 44 | Project Documentation | Inclusive language | 2 - High | `U-remove-legacy-branch-names-and-minimizing-language.md` | Prefer "cancel" over "abort" in Live Migration prose | -| 45 | Project Documentation | Inclusive language | 3 - Backlog | `U-remove-legacy-branch-names-and-minimizing-language.md` | Use tagged or permalink URLs for upstream project links | -| 46 | Contributor documentation | Communication methods documented | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | -| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | -| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Add repository and social links to every page | -| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | -| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Standardize on the `good first issue` label | -| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Seed and maintain a pool of beginner issues | -| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Triage the open issue backlog | -| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Standardize on the `good first issue` label | -| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Triage the open issue backlog | -| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Seed and maintain a pool of beginner issues | -| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Publish a documentation triage cadence and give documentation a SIG home | -| 57 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Making your first documentation change" walkthrough | -| 58 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | -| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | -| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add "Where to ask for help" and direct links to beginner issues | -| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Contributing to the code" subsection and document mentoring | -| 62 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-a-documentation-contributor-guide-and-review-process.md` | Add a "Contributing to the code" subsection and document mentoring | -| 63 | Contributor documentation | Project governance documentation | 2 - High | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add a Governance section to the Community page | -| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Explain how the project is run on the Contributing page | -| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-a-documentation-contributor-guide-and-review-process.md` | Explain how the project is run on the Contributing page | +| 1 | Project Documentation | Information architecture | 2 - High | `U-create-getting-started-path.md` | Add a Getting Started page after Architecture | +| 2 | Project Documentation | Information architecture | 2 - High | `U-create-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | +| 3 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps.md` | Add the Plugins page to the navigation and delete the duplicate page | +| 4 | Project Documentation | Information architecture | 2 - High | `U-document-v19-features.md`
`U-document-v19-features.md`
`U-document-v19-features.md` | Document the VirtualMachineBackup API
Document the CrossArchitectureVirtualization feature gate
Document masquerade PortRanges and MigrationPolicy compression | +| 5 | Project Documentation | Information architecture | 2 - High | `U-document-v19-features.md` | Create a virtctl command reference | +| 6 | Project Documentation | Information architecture | 2 - High | `U-document-v19-features.md` | Add a feature-gate table | +| 7 | Project Documentation | Information architecture | 2 - High | `add-troubleshooting-page.md` | (standalone issue) | +| 8 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps.md` | Add a landing page to each of the Compute, Network, and Storage sections | +| 9 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps.md` | Rename API-centric page titles to user goals | +| 10 | Project Documentation | Information architecture | 3 - Backlog | `U-fix-navigation-gaps.md` | Group legacy workload mechanisms under a Legacy heading | +| 11 | Project Documentation | Information architecture | 2 - High | `U-fix-navigation-gaps.md` | Remove or archive legacy installation content | +| 12 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps.md` | Add the Plugins page to the navigation and delete the duplicate page | +| 13 | Project Documentation | Information architecture | 1 - Urgent | `U-fix-navigation-gaps.md` | Move Release Notes out of the middle of the main navigation | +| 14 | Project Documentation | New user content | 2 - High | `U-create-getting-started-path.md` | Add a Getting Started page after Architecture | +| 15 | Project Documentation | New user content | 2 - High | `U-create-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | +| 16 | Project Documentation | New user content | 1 - Urgent | `U-create-getting-started-path.md` | End the Installation page with a Next steps section | +| 17 | Project Documentation | New user content | 2 - High | `U-create-getting-started-path.md` | Restructure the Installation page so the core procedure comes first | +| 18 | Project Documentation | New user content | 2 - High | `U-create-getting-started-path.md` | Expand the virtctl page and rename it "Installing virtctl" | +| 19 | Project Documentation | New user content | 2 - High | `U-create-getting-started-path.md` | Rewrite Basic Use as "Your first VirtualMachine" | +| 20 | Project Documentation | New user content | 1 - Urgent | `U-mkdocs-improvements.md` | Enable code copy and search features in the theme | +| 21 | Project Documentation | New user content | 3 - Backlog | `U-accessibility-improvements.md`
`U-accessibility-improvements.md` | Convert code blocks on the new-user path
Convert code blocks on the longest reference pages | +| 22 | Project Documentation | New user content | 3 - Backlog | `U-create-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | +| 23 | Project Documentation | New user content | 1 - Urgent | `U-create-getting-started-path.md` | Point newcomers at the Getting Started page from Welcome and Quickstarts | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-publish-versioned-docs.md` | Document the content versioning model | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-publish-versioned-docs.md` | Publish versioned documentation with a version selector | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-document-v19-features.md` | Standardize the feature-state admonition | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-publish-versioned-docs.md` | Document the release-notes update process | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | `U-mkdocs-improvements.md` | Enable code copy and search features in the theme | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | `U-publish-versioned-docs.md` | Add a localization statement | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | `U-publish-versioned-docs.md` | Ask about a site-wide search | +| 31 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | Expand CONTRIBUTING.md into a full documentation contributor guide | +| 32 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | Name maintainers and route reviews to subject-matter experts | +| 33 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | Write a documentation style guide | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-contributor-guide.md` | Add a pull request template | +| 35 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | Name maintainers and route reviews to subject-matter experts | +| 36 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | Name maintainers and route reviews to subject-matter experts | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | `U-build-contributor-guide.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | +| 38 | Project Documentation | Content creation processes | 2 - High | `U-build-contributor-guide.md` | State the code-freeze requirement and a stale-PR policy, and triage open pull requests | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | `U-inclusive-language-updates.md`
`U-inclusive-language-updates.md` | Reword minimizing language on the five pages with the most occurrences
Reword minimizing language across the remaining pages | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | `U-build-contributor-guide.md` | Write a documentation style guide | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | `U-inclusive-language-updates.md` | Add an automated check for minimizing language | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | `U-inclusive-language-updates.md` | Update legacy branch-name links and the Presets example | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | `U-inclusive-language-updates.md` | Update legacy branch-name links and the Presets example | +| 44 | Project Documentation | Inclusive language | 2 - High | `U-inclusive-language-updates.md` | Prefer "cancel" over "abort" in Live Migration prose | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | `U-inclusive-language-updates.md` | Use tagged or permalink URLs for upstream project links | +| 46 | Contributor documentation | Communication methods documented | 2 - High | `U-document-community-channels.md` | Add a Community and communication page to the guide | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | `U-document-community-channels.md` | Add a Community and communication page to the guide | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-mkdocs-improvements.md` | Add repository and social links to every page | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | `U-document-community-channels.md` | Add a Community and communication page to the guide | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | `U-document-community-channels.md` | Standardize on the `good first issue` label | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels.md` | Seed and maintain a pool of beginner issues | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels.md` | Triage the open issue backlog | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels.md` | Standardize on the `good first issue` label | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels.md` | Triage the open issue backlog | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | `U-document-community-channels.md` | Seed and maintain a pool of beginner issues | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | `U-document-community-channels.md` | Publish a documentation triage cadence and give documentation a SIG home | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-contributor-guide.md` | Add a "Making your first documentation change" walkthrough | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-contributor-guide.md` | Add "Where to ask for help" and direct links to beginner issues | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-contributor-guide.md` | Add "Where to ask for help" and direct links to beginner issues | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | `U-build-contributor-guide.md` | Add "Where to ask for help" and direct links to beginner issues | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | `U-build-contributor-guide.md` | Add a "Contributing to the code" subsection and document mentoring | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | `U-build-contributor-guide.md` | Add a "Contributing to the code" subsection and document mentoring | +| 63 | Contributor documentation | Project governance documentation | 2 - High | `U-fix-kubevirt-io-gaps.md` | Add a Governance section to the Community page | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-contributor-guide.md` | Explain how the project is run on the Contributing page | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | `U-build-contributor-guide.md` | Explain how the project is run on the Contributing page | | 66 | Contributor documentation | Project governance documentation | 2 - High | — | Not an issue — asks maintainers to audit SIG charters and `sigs.yaml` in `kubevirt/community`; a governance action outside the documentation scope. | -| 67 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Document where documentation lives | -| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Move user-facing content out of kubevirt/kubevirt/docs | -| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Triage the CDI documentation the guide links to | -| 70 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Record the repository and toolchain decisions | -| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | `U-fix-navigation-gaps-and-reorganize-information-architecture.md` | Give the API reference a visible home in the user guide | -| 72 | Website & Infrastructure | Website requirements | 2 - High | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md` | (standalone issue) | -| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add the © symbol and the missing root repository files | -| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Point vendor logos at KubeVirt-specific pages | -| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | -| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add the © symbol and the missing root repository files | -| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | `bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | -| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Fix header and link contrast and align the brand color | -| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Replace the ASCII architecture diagram with an accessible diagram | -| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Convert code blocks on the new-user path | -| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Verify wide tables on mobile and add table captions | -| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Split Disks and Volumes by volume type
Split Interfaces and Networks and Live Migration
Split Release Notes by minor release | -| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md`
`U-improve-accessibility-mobile-usability-and-code-blocks.md` | Set the logo alt text and remove unused configuration and assets
Verify wide tables on mobile and add table captions | -| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Add an accessibility check to CI | -| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Publish a short brand reference | -| 86 | Website & Infrastructure | Branding and design | 2 - High | `U-improve-accessibility-mobile-usability-and-code-blocks.md` | Fix header and link contrast and align the brand color | -| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Add repository and social links to every page | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-ownership.md` | Document where documentation lives | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-ownership.md` | Move user-facing content out of kubevirt/kubevirt/docs | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | `U-document-site-ownership.md` | Triage the CDI documentation the guide links to | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | `U-document-site-ownership.md` | Record the repository and toolchain decisions | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | `U-fix-navigation-gaps.md` | Give the API reference a visible home in the user guide | +| 72 | Website & Infrastructure | Website requirements | 2 - High | `fix-footer-cncf-compliance.md` | (standalone issue) | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-gaps.md` | Add the © symbol and the missing root repository files | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | `U-fix-kubevirt-io-gaps.md` | Point vendor logos at KubeVirt-specific pages | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | `fix-footer-cncf-compliance.md`
`U-fix-kubevirt-io-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | `U-fix-kubevirt-io-gaps.md` | Add the © symbol and the missing root repository files | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | `fix-footer-cncf-compliance.md`
`U-fix-kubevirt-io-gaps.md` | (standalone issue, user guide)
Add the © symbol and the missing root repository files (website) | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | `U-accessibility-improvements.md` | Fix header and link contrast and align the brand color | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-accessibility-improvements.md` | Replace the ASCII architecture diagram with an accessible diagram | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-accessibility-improvements.md` | Convert code blocks on the new-user path | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-accessibility-improvements.md` | Verify wide tables on mobile and add table captions | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-accessibility-improvements.md`
`U-accessibility-improvements.md`
`U-accessibility-improvements.md` | Split Disks and Volumes by volume type
Split Interfaces and Networks and Live Migration
Split Release Notes by minor release | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | `U-mkdocs-improvements.md`
`U-accessibility-improvements.md` | Set the logo alt text and remove unused configuration and assets
Verify wide tables on mobile and add table captions | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | `U-accessibility-improvements.md` | Add an accessibility check to CI | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | `U-fix-kubevirt-io-gaps.md` | Publish a short brand reference | +| 86 | Website & Infrastructure | Branding and design | 2 - High | `U-accessibility-improvements.md` | Fix header and link contrast and align the brand color | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-mkdocs-improvements.md` | Add repository and social links to every page | | 88 | Website & Infrastructure | Branding and design | 3 - Backlog | — | Not an issue — optional logo-variant preference with minimal reader impact. | -| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Set the logo alt text and remove unused configuration and assets | -| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Set the logo alt text and remove unused configuration and assets | -| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Link the existing CNCF case studies from the landing page | -| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Show adopter use cases on the logo wall | -| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Create an adopters page | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-mkdocs-improvements.md` | Set the logo alt text and remove unused configuration and assets | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | `U-mkdocs-improvements.md` | Set the logo alt text and remove unused configuration and assets | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-fix-kubevirt-io-gaps.md` | Link the existing CNCF case studies from the landing page | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | `U-fix-kubevirt-io-gaps.md` | Show adopter use cases on the logo wall | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-gaps.md` | Create an adopters page | | 94 | Website & Infrastructure | Case studies/social proof | 2 - High | — | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | -| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Add blog categories beyond news and uncategorized | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | `U-fix-kubevirt-io-gaps.md` | Add blog categories beyond news and uncategorized | | 96 | Website & Infrastructure | Case studies/social proof | 2 - High | — | Not an issue — a publishing-cadence commitment for the blog is a process decision, not a documentation change. | -| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | -| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Add a Community and communication page to the guide | -| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | Enable analytics on the user guide | -| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Load analytics only in production (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | -| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md`
`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Make preview builds reproducible and non-indexable (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | -| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Fix robots.txt, gate analytics to production, and block indexing of previews | -| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Make preview builds reproducible and non-indexable | -| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` | Index non-blog pages in site search and cross-link the two searches | -| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Site infrastructure section to the README | -| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-enable-analytics-on-the-user-guide-and-fix-broken-links.md` | Set up a recurring 404 report and feed it into the redirects map | -| 107 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Site infrastructure section to the README | -| 108 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-community-channels-and-maintain-a-beginner-issue-backlog.md` | Publish a documentation triage cadence and give documentation a SIG home | -| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels.md` | Add a Community and communication page to the guide | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | `U-document-community-channels.md` | Add a Community and communication page to the guide | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics.md` | Enable analytics on the user guide | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-enable-analytics.md`
`U-fix-kubevirt-io-gaps.md` | Load analytics only in production (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-mkdocs-improvements.md`
`U-fix-kubevirt-io-gaps.md` | Make preview builds reproducible and non-indexable (user guide)
Fix robots.txt, gate analytics to production, and block indexing of previews (website) | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-fix-kubevirt-io-gaps.md` | Fix robots.txt, gate analytics to production, and block indexing of previews | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | `U-mkdocs-improvements.md` | Make preview builds reproducible and non-indexable | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-fix-kubevirt-io-gaps.md` | Index non-blog pages in site search and cross-link the two searches | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | `U-document-site-ownership.md` | Add a Site infrastructure section to the README | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | `U-enable-analytics.md` | Set up a recurring 404 report and feed it into the redirects map | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-ownership.md` | Add a Site infrastructure section to the README | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-community-channels.md` | Publish a documentation triage cadence and give documentation a SIG home | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-ownership.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | | 110 | Website & Infrastructure | Maintenance planning | 2 - High | — | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by the beginner issue backlog issue. | -| 111 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Record the repository and toolchain decisions | -| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | `U-apply-low-effort-mkdocs-and-build-configuration-improvements.md` | Make preview builds reproducible and non-indexable | -| 113 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Add a Strict-Transport-Security header or record the gap | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-infrastructure-ownership-and-documentation-boundaries.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-ownership.md` | Record the repository and toolchain decisions | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | `U-mkdocs-improvements.md` | Make preview builds reproducible and non-indexable | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | `U-document-site-ownership.md` | Add a Strict-Transport-Security header or record the gap | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | `U-document-site-ownership.md` | Publish a maintainer ladder and keep OWNERS_ALIASES current | ## Priority adjustments @@ -146,19 +146,19 @@ Umbrella labels follow the highest-priority sub-issue, with these exceptions: | Recommendation | CSV priority | Issue label | Reason | |---|---|---|---| -| 42, 43 (legacy `master` links and node-name example) | 1 - Urgent | high (`U-remove-legacy-branch-names-and-minimizing-language.md`) | Two small fixes in an umbrella whose remaining work is backlog-priority prose cleanup. They are the first sub-issue so they can be done immediately; split them out if the umbrella's label matters. | -| 81, 83 (mobile table check and captions) | 1 - Urgent | high (`U-improve-accessibility-mobile-usability-and-code-blocks.md`) | The logo alt-text half of 83 is in the urgent configuration issue. The remaining verification and caption work is small and sits alongside the other accessibility fixes. | -| 8, 9, 10 (landing pages, title renames, Legacy grouping) | 3 - Backlog | urgent (`U-fix-navigation-gaps-and-reorganize-information-architecture.md`) | Bundled with urgent navigation fixes because they touch the same `.nav.yml` files; the sub-issues can be deferred independently. | -| 22 (Quickstarts introduction) | 3 - Backlog | urgent (`U-create-a-new-user-getting-started-path.md`) | Combined with the urgent Welcome "Start here" link because both are one-paragraph edits to entry pages. | -| 53, 54, 55 (`help wanted` guidance, `lifecycle/frozen`, issue checklist) | 3 - Backlog | urgent (`U-document-community-channels-and-maintain-a-beginner-issue-backlog.md`) | Bundled into the label-standardization, triage, and seeding sub-issues they naturally belong to. | -| 74, 85, 95, 104 (vendor logos, brand reference, blog categories, site search) | 3 - Backlog | urgent (`U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md`) | Grouped with the urgent website compliance fixes because all land in `kubevirt/kubevirt.github.io`; these are the last four sub-issues and can be deferred. | -| 27, 29 (release-notes process, localization) | 3 - Backlog | high (`U-document-the-versioning-model-and-publish-versioned-documentation.md`) | Both are short `CONTRIBUTING.md` additions that belong next to the versioning model. | -| 106 (404 report) | 3 - Backlog | high (`U-enable-analytics-on-the-user-guide-and-fix-broken-links.md`) | Depends on the analytics sub-issues in the same umbrella. | -| 68, 69, 109, 114 (content audits, maintainer ladder, OWNERS_ALIASES) | 3 - Backlog | high (`U-document-site-infrastructure-ownership-and-documentation-boundaries.md`) | Grouped with the ownership and boundary documentation they implement. | +| 42, 43 (legacy `master` links and node-name example) | 1 - Urgent | high (`U-inclusive-language-updates.md`) | Two small fixes in an umbrella whose remaining work is backlog-priority prose cleanup. They are the first sub-issue so they can be done immediately; split them out if the umbrella's label matters. | +| 81, 83 (mobile table check and captions) | 1 - Urgent | high (`U-accessibility-improvements.md`) | The logo alt-text half of 83 is in the urgent configuration issue. The remaining verification and caption work is small and sits alongside the other accessibility fixes. | +| 8, 9, 10 (landing pages, title renames, Legacy grouping) | 3 - Backlog | urgent (`U-fix-navigation-gaps.md`) | Bundled with urgent navigation fixes because they touch the same `.nav.yml` files; the sub-issues can be deferred independently. | +| 22 (Quickstarts introduction) | 3 - Backlog | urgent (`U-create-getting-started-path.md`) | Combined with the urgent Welcome "Start here" link because both are one-paragraph edits to entry pages. | +| 53, 54, 55 (`help wanted` guidance, `lifecycle/frozen`, issue checklist) | 3 - Backlog | urgent (`U-document-community-channels.md`) | Bundled into the label-standardization, triage, and seeding sub-issues they naturally belong to. | +| 74, 85, 95, 104 (vendor logos, brand reference, blog categories, site search) | 3 - Backlog | urgent (`U-fix-kubevirt-io-gaps.md`) | Grouped with the urgent website compliance fixes because all land in `kubevirt/kubevirt.github.io`; these are the last four sub-issues and can be deferred. | +| 27, 29 (release-notes process, localization) | 3 - Backlog | high (`U-publish-versioned-docs.md`) | Both are short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| 106 (404 report) | 3 - Backlog | high (`U-enable-analytics.md`) | Depends on the analytics sub-issues in the same umbrella. | +| 68, 69, 109, 114 (content audits, maintainer ladder, OWNERS_ALIASES) | 3 - Backlog | high (`U-document-site-ownership.md`) | Grouped with the ownership and boundary documentation they implement. | ## Notes for the writer -- `U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md` describes changes to `kubevirt/kubevirt.github.io`. Its `repo` is set to the user guide per the instructions; change it to `https://github.com/kubevirt/kubevirt.github.io/issues` if the upload should target the website repository directly. +- `U-fix-kubevirt-io-gaps.md` describes changes to `kubevirt/kubevirt.github.io`. Its `repo` is set to the user guide per the instructions; change it to `https://github.com/kubevirt/kubevirt.github.io/issues` if the upload should target the website repository directly. - Recommendations 75, 77, 100, and 101 each have a user-guide half and a website half and appear in two files. diff --git a/analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md b/analyses/2026/kubevirt/issues/U-accessibility-improvements.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-improve-accessibility-mobile-usability-and-code-blocks.md rename to analyses/2026/kubevirt/issues/U-accessibility-improvements.md diff --git a/analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-build-a-documentation-contributor-guide-and-review-process.md rename to analyses/2026/kubevirt/issues/U-build-contributor-guide.md diff --git a/analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-create-a-new-user-getting-started-path.md rename to analyses/2026/kubevirt/issues/U-create-getting-started-path.md diff --git a/analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md b/analyses/2026/kubevirt/issues/U-document-community-channels.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-document-community-channels-and-maintain-a-beginner-issue-backlog.md rename to analyses/2026/kubevirt/issues/U-document-community-channels.md diff --git a/analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md b/analyses/2026/kubevirt/issues/U-document-site-ownership.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-document-site-infrastructure-ownership-and-documentation-boundaries.md rename to analyses/2026/kubevirt/issues/U-document-site-ownership.md diff --git a/analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md b/analyses/2026/kubevirt/issues/U-document-v19-features.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-document-v1-9-features-and-add-reference-pages.md rename to analyses/2026/kubevirt/issues/U-document-v19-features.md diff --git a/analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md b/analyses/2026/kubevirt/issues/U-enable-analytics.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-enable-analytics-on-the-user-guide-and-fix-broken-links.md rename to analyses/2026/kubevirt/issues/U-enable-analytics.md diff --git a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-fix-kubevirt-io-compliance-seo-and-adopter-content-gaps.md rename to analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md diff --git a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-fix-navigation-gaps-and-reorganize-information-architecture.md rename to analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md diff --git a/analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md b/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-remove-legacy-branch-names-and-minimizing-language.md rename to analyses/2026/kubevirt/issues/U-inclusive-language-updates.md diff --git a/analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md b/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-apply-low-effort-mkdocs-and-build-configuration-improvements.md rename to analyses/2026/kubevirt/issues/U-mkdocs-improvements.md diff --git a/analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md b/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md similarity index 100% rename from analyses/2026/kubevirt/issues/U-document-the-versioning-model-and-publish-versioned-documentation.md rename to analyses/2026/kubevirt/issues/U-publish-versioned-docs.md diff --git a/analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md b/analyses/2026/kubevirt/issues/add-troubleshooting-page.md similarity index 100% rename from analyses/2026/kubevirt/issues/add-a-user-facing-troubleshooting-page.md rename to analyses/2026/kubevirt/issues/add-troubleshooting-page.md diff --git a/analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md b/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md similarity index 100% rename from analyses/2026/kubevirt/issues/bring-the-user-guide-footer-and-repository-files-into-cncf-compliance.md rename to analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md From 86fe59d1af7c7bddb9b042cb3bc6674251ea0da2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 12 Oct 2026 19:37:00 -0700 Subject: [PATCH 03/31] spell and format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 8 +- .../issues/U-accessibility-improvements.md | 87 ++++++++++---- .../issues/U-build-contributor-guide.md | 108 +++++++++++++----- .../issues/U-create-getting-started-path.md | 85 ++++++++++---- .../issues/U-document-community-channels.md | 66 ++++++++--- .../issues/U-document-site-ownership.md | 68 ++++++++--- .../issues/U-document-v19-features.md | 46 ++++++-- .../kubevirt/issues/U-enable-analytics.md | 25 +++- .../kubevirt/issues/U-fix-kubevirt-io-gaps.md | 83 ++++++++++---- .../kubevirt/issues/U-fix-navigation-gaps.md | 61 +++++++--- .../issues/U-inclusive-language-updates.md | 48 ++++++-- .../kubevirt/issues/U-mkdocs-improvements.md | 49 +++++--- .../issues/U-publish-versioned-docs.md | 47 ++++++-- .../issues/add-troubleshooting-page.md | 33 ++++-- .../issues/fix-footer-cncf-compliance.md | 28 +++-- 15 files changed, 642 insertions(+), 200 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 8082e7f8..84fe06b6 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -23,7 +23,7 @@ This report maps every recommendation in `.github/input/ai-ranked-recommendation ## Recommendation mapping -| # | Section | Area | CSV priority | Issue file | Sub-issue | + ## Priority adjustments Umbrella labels follow the highest-priority sub-issue, with these exceptions: -| Recommendation | CSV priority | Issue label | Reason | + ## Notes for the writer diff --git a/analyses/2026/kubevirt/issues/U-accessibility-improvements.md b/analyses/2026/kubevirt/issues/U-accessibility-improvements.md index c3faf3cf..5e44d036 100644 --- a/analyses/2026/kubevirt/issues/U-accessibility-improvements.md +++ b/analyses/2026/kubevirt/issues/U-accessibility-improvements.md @@ -6,9 +6,18 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -The guide's brand teal header and link color fall below the 4.5:1 contrast ratio that WCAG AA requires, the Architecture page's stack diagram is ASCII art that screen readers cannot interpret, wide tables may overflow on phones, and most code blocks use `$`-prefixed indented formatting that pastes badly and scrolls horizontally. Several pages exceed 500 lines, which makes them hard to navigate on any device. - -The sub-issues below fix the contrast and diagram problems, modernize the code blocks starting with the new-user path, split the longest pages, and add an automated check so the fixes stay fixed. Enable `content.code.copy` first (tracked in the configuration quick-wins issue) so the code block work shows its full benefit. +The guide's brand teal header and link color fall below the 4.5:1 contrast ratio +that WCAG AA requires, the Architecture page's stack diagram is ASCII art that +screen readers cannot interpret, wide tables may overflow on phones, and most +code blocks use `$`-prefixed indented formatting that pastes badly and scrolls +horizontally. Several pages exceed 500 lines, which makes them hard to navigate +on any device. + +The sub-issues below fix the contrast and diagram problems, modernize the code +blocks starting with the new-user path, split the longest pages, and add an +automated check so the fixes stay fixed. Enable `content.code.copy` first +(tracked in the configuration quick-wins issue) so the code block work shows its +full benefit. ## Sub-issues @@ -16,61 +25,99 @@ The sub-issues below fix the contrast and diagram problems, modernize the code b In `docs/stylesheets/extra.css`: -- Darken `--md-primary-fg-color` to a teal that gives at least 4.5:1 against white, or keep the brand teal for decorative elements only and set the header and tab text to a dark foreground. -- Replace the `filter: brightness(80%)` link rule with explicit `--md-typeset-a-color` values per color scheme, each checked against 4.5:1. -- Replace the ad hoc `#0db2b6` primary with a value from the main site's documented `$kv-color--green-*` scale, for example `#00aab2`, or ask the website maintainers to add `#0db2b6` to the scale so both properties draw from one list. +- Darken `--md-primary-fg-color` to a teal that gives at least 4.5:1 against + white, or keep the brand teal for decorative elements only and set the header + and tab text to a dark foreground. +- Replace the `filter: brightness(80%)` link rule with explicit + `--md-typeset-a-color` values per color scheme, each checked against 4.5:1. +- Replace the ad hoc `#0db2b6` primary with a value from the main site's + documented `$kv-color--green-*` scale, for example `#00aab2`, or ask the + website maintainers to add `#0db2b6` to the scale so both properties draw from + one list. Verify both light and dark schemes with a contrast checker. -Done when: header text and links meet 4.5:1 in both schemes and the primary color matches the main site's scale. +Done when: header text and links meet 4.5:1 in both schemes and the primary +color matches the main site's scale. ### Replace the ASCII architecture diagram with an accessible diagram -On the Architecture page (`docs/architecture.md`), replace the ASCII stack diagram with a Mermaid diagram (enable `pymdownx.superfences` custom fences for `mermaid` in `mkdocs.yml`) or an image with descriptive alt text. Add a one-paragraph prose description of the layers so screen reader and mobile users get the same information. +On the Architecture page (`docs/architecture.md`), replace the ASCII stack +diagram with a Mermaid diagram (enable `pymdownx.superfences` custom fences for +`mermaid` in `mkdocs.yml`) or an image with descriptive alt text. Add a +one-paragraph prose description of the layers so screen reader and mobile users +get the same information. Done when: the diagram renders on mobile and its content is available as text. ### Verify wide tables on mobile and add table captions -On a phone, check that the tables on `docs/cluster_admin/feature_gate_status_on_Arm64.md` and `docs/cluster_admin/device_status_on_Arm64.md` scroll horizontally rather than overflowing the page. If they overflow, remove the `display: table; width: max-content` override from `extra.css` or scope it to specific tables with `attr_list` classes. Add a short caption or introductory sentence above each wide status table stating what it shows. +On a phone, check that the tables on +`docs/cluster_admin/feature_gate_status_on_Arm64.md` and +`docs/cluster_admin/device_status_on_Arm64.md` scroll horizontally rather than +overflowing the page. If they overflow, remove the +`display: table; width: max-content` override from `extra.css` or scope it to +specific tables with `attr_list` classes. Add a short caption or introductory +sentence above each wide status table stating what it shows. -Done when: no table overflows on a 375 px viewport and each status table has a caption. +Done when: no table overflows on a 375 px viewport and each status table has a +caption. ### Convert code blocks on the new-user path to fenced blocks -On Installation, Installing virtctl, Basic Use, and Lifecycle, convert `$`-prefixed indented code blocks to fenced `shell` blocks without prompt characters. Place example output in a separate block or a `title="Output"` annotation so commands paste cleanly. Break commands over 100 characters across lines with `\` continuations. +On Installation, Installing virtctl, Basic Use, and Lifecycle, convert +`$`-prefixed indented code blocks to fenced `shell` blocks without prompt +characters. Place example output in a separate block or a `title="Output"` +annotation so commands paste cleanly. Break commands over 100 characters across +lines with `\` continuations. -Done when: every command on these pages can be copied and pasted without editing. +Done when: every command on these pages can be copied and pasted without +editing. ### Convert code blocks on the longest reference pages -Apply the same conversion to Disks and Volumes (`docs/storage/disks_and_volumes.md`), Export API (`docs/storage/export_api.md`), Interfaces and Networks (`docs/network/interfaces_and_networks.md`), and Live Migration (`docs/compute/live_migration.md`). +Apply the same conversion to Disks and Volumes +(`docs/storage/disks_and_volumes.md`), Export API +(`docs/storage/export_api.md`), Interfaces and Networks +(`docs/network/interfaces_and_networks.md`), and Live Migration +(`docs/compute/live_migration.md`). Done when: these four pages contain no `$`-prefixed indented code blocks. ### Split Disks and Volumes by volume type -Split `docs/storage/disks_and_volumes.md` into an overview page plus one page per volume type or group of related types. Add the new pages to `docs/storage/.nav.yml` and redirects for any anchors that external pages link to. +Split `docs/storage/disks_and_volumes.md` into an overview page plus one page +per volume type or group of related types. Add the new pages to +`docs/storage/.nav.yml` and redirects for any anchors that external pages link +to. Done when: no resulting page exceeds about 500 lines and existing links resolve. ### Split Interfaces and Networks and Live Migration -- Split `docs/network/interfaces_and_networks.md` so binding methods and network attachment are separate pages. -- Move the migration strategies and network configuration sections of `docs/compute/live_migration.md` to sub-pages. +- Split `docs/network/interfaces_and_networks.md` so binding methods and network + attachment are separate pages. +- Move the migration strategies and network configuration sections of + `docs/compute/live_migration.md` to sub-pages. Update the `.nav.yml` files and add redirects. -Done when: each resulting page is under about 500 lines and existing links resolve. +Done when: each resulting page is under about 500 lines and existing links +resolve. ### Split Release Notes by minor release -Split `docs/release_notes.md` into one page per minor release, or paginate it, and set the Release Notes navigation entry to open the newest release. Update `update_changelog.sh` so regeneration writes to the new structure. +Split `docs/release_notes.md` into one page per minor release, or paginate it, +and set the Release Notes navigation entry to open the newest release. Update +`update_changelog.sh` so regeneration writes to the new structure. -Done when: the newest release opens first and older releases load on separate pages. +Done when: the newest release opens first and older releases load on separate +pages. ### Add an accessibility check to CI -Add an accessibility check to the Makefile and the Prow pre-submit, for example `pa11y-ci` or Lighthouse run against the built site for a sample of pages, so contrast regressions are caught in pull requests. +Add an accessibility check to the Makefile and the Prow pre-submit, for example +`pa11y-ci` or Lighthouse run against the built site for a sample of pages, so +contrast regressions are caught in pull requests. Done when: a pull request that lowers contrast below 4.5:1 fails the check. diff --git a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md index fdd1d217..18ab1ac2 100644 --- a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md +++ b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md @@ -6,21 +6,37 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -`CONTRIBUTING.md` is a pointer, the Contributing page lists links without explaining them, and there is no style guide, pull request template, or named documentation maintainer. New contributors cannot tell how to make a change, who reviews it, or what "done" looks like, and twelve pull requests sit open. +`CONTRIBUTING.md` is a pointer, the Contributing page lists links without +explaining them, and there is no style guide, pull request template, or named +documentation maintainer. New contributors cannot tell how to make a change, who +reviews it, or what "done" looks like, and twelve pull requests sit open. -The sub-issues below turn `CONTRIBUTING.md` and `docs/contributing.md` into a complete contributor guide, add the supporting files that make reviews predictable, and route reviews to the right people. The Thanos "How to contribute to docs" page and the NATS `MAINTAINERS` file are good models. +The sub-issues below turn `CONTRIBUTING.md` and `docs/contributing.md` into a +complete contributor guide, add the supporting files that make reviews +predictable, and route reviews to the right people. The Thanos "How to +contribute to docs" page and the NATS `MAINTAINERS` file are good models. ## Sub-issues ### Expand CONTRIBUTING.md into a full documentation contributor guide -Rewrite `CONTRIBUTING.md` to cover the full lifecycle: how to propose a change, how to build and test locally (move the build steps from the README here), what happens after opening a pull request (labels, `/lgtm`, `/approve`, expected turnaround), when to add a redirect to `mkdocs.yml`, and when a change needs a cherry-pick to a `release-vX.Y-stable` branch. Summarize the key points on the Contributing page and link to the full guide. +Rewrite `CONTRIBUTING.md` to cover the full lifecycle: how to propose a change, +how to build and test locally (move the build steps from the README here), what +happens after opening a pull request (labels, `/lgtm`, `/approve`, expected +turnaround), when to add a redirect to `mkdocs.yml`, and when a change needs a +cherry-pick to a `release-vX.Y-stable` branch. Summarize the key points on the +Contributing page and link to the full guide. -Done when: a first-time contributor can go from clone to merged PR using only this file. +Done when: a first-time contributor can go from clone to merged PR using only +this file. ### Add a "Making your first documentation change" walkthrough -Add a section to `docs/contributing.md` that walks through the mechanics end to end: find or file an issue, comment to claim it, fork and branch, edit under `docs/` and update `.nav.yml`, run `make check_spelling` and `make check_links`, sign off with `git commit -s`, open the pull request, and what to expect from Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. +Add a section to `docs/contributing.md` that walks through the mechanics end to +end: find or file an issue, comment to claim it, fork and branch, edit under +`docs/` and update `.nav.yml`, run `make check_spelling` and `make check_links`, +sign off with `git commit -s`, open the pull request, and what to expect from +Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. Done when: every step names the command or UI action to take. @@ -28,58 +44,92 @@ Done when: every step names the command or UI action to take. On `docs/contributing.md`, and repeated in `CONTRIBUTING.md`: -- Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and `#virtualization` for usage questions, and link the Slack invitation page. -- State that the weekly community meeting includes newcomer introductions, with the day, time, and meeting link. +- Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and + `#virtualization` for usage questions, and link the Slack invitation page. +- State that the weekly community meeting includes newcomer introductions, with + the day, time, and meeting link. - Identify the documentation approvers or a docs contact. -- Replace the generic "look for good-first-issue" advice with direct links to the filtered issue list for each repository. -- Link the `kubevirt/community` resources newcomers need: the SIG list, the help-wanted guide, the community meeting document, and the `MAINTAINERS` file. +- Replace the generic "look for good-first-issue" advice with direct links to + the filtered issue list for each repository. +- Link the `kubevirt/community` resources newcomers need: the SIG list, the + help-wanted guide, the community meeting document, and the `MAINTAINERS` file. -Done when: a newcomer can find a person to ask and an issue to pick up from this page. +Done when: a newcomer can find a person to ask and an issue to pick up from this +page. ### Explain how the project is run on the Contributing page -Above the "Important community resources" list on `docs/contributing.md`, add a short "How the project is run" paragraph that names the maintainer group, explains that work is organized in SIGs, and states that decisions default to lazy consensus. Give each link in the resource list a one-sentence description of what the reader will find. +Above the "Important community resources" list on `docs/contributing.md`, add a +short "How the project is run" paragraph that names the maintainer group, +explains that work is organized in SIGs, and states that decisions default to +lazy consensus. Give each link in the resource list a one-sentence description +of what the reader will find. Done when: a newcomer understands the structure before following any link. ### Add a "Contributing to the code" subsection and document mentoring -Add a subsection to `docs/contributing.md` that summarizes the `kubevirt/kubevirt` path in three or four steps: read its `CONTRIBUTING.md`, follow `docs/getting-started.md` to build and run a local cluster, pick an issue, open a draft PR. +Add a subsection to `docs/contributing.md` that summarizes the +`kubevirt/kubevirt` path in three or four steps: read its `CONTRIBUTING.md`, +follow `docs/getting-started.md` to build and run a local cluster, pick an +issue, open a draft PR. -Ask the community whether a mentoring or buddy arrangement exists for first-time contributors. The help-wanted guide promises "extra assistance" on `good first issue` items; state how to request it. +Ask the community whether a mentoring or buddy arrangement exists for first-time +contributors. The help-wanted guide promises "extra assistance" on +`good first issue` items; state how to request it. -Done when: code-minded newcomers see a clear next step and know how to ask for help. +Done when: code-minded newcomers see a clear next step and know how to ask for +help. ### Write a documentation style guide -Add a short style guide, linked from `CONTRIBUTING.md` and the Contributing page, that covers: +Add a short style guide, linked from `CONTRIBUTING.md` and the Contributing +page, that covers: -- Page structure: title, short concept, feature-state banner, procedure, related links. +- Page structure: title, short concept, feature-state banner, procedure, related + links. - The standard feature-state admonition. -- Code block conventions: fenced blocks, no `$` prompts, output in a separate block. -- Kubernetes object capitalization (VirtualMachine, VirtualMachineInstance) and file naming. -- A rule that discourages "simple", "simply", "easy", "easily", "just", and "obviously", with a one-line explanation of why. +- Code block conventions: fenced blocks, no `$` prompts, output in a separate + block. +- Kubernetes object capitalization (VirtualMachine, VirtualMachineInstance) and + file naming. +- A rule that discourages "simple", "simply", "easy", "easily", "just", and + "obviously", with a one-line explanation of why. Done when: a reviewer can point to the guide for each common review comment. ### Add a pull request template -Add `.github/PULL_REQUEST_TEMPLATE.md` with a checklist: `.nav.yml` updated for new pages, redirect added for moved pages, spelling and link checks run, feature-state banner present, and the related `kubevirt/kubevirt` PR or VEP linked. +Add `.github/PULL_REQUEST_TEMPLATE.md` with a checklist: `.nav.yml` updated for +new pages, redirect added for moved pages, spelling and link checks run, +feature-state banner present, and the related `kubevirt/kubevirt` PR or VEP +linked. Done when: new pull requests open with the checklist. ### State the code-freeze requirement and a stale-PR policy, and triage open pull requests -- On the Contributing page, state that the VEP checklist requires the docs PR to be merged by code freeze. -- Add a stale-PR policy to `CONTRIBUTING.md` so contributors know what to expect. -- Triage the currently open pull requests: merge or close the oldest, and leave a comment on each remaining one stating what it needs. +- On the Contributing page, state that the VEP checklist requires the docs PR to + be merged by code freeze. +- Add a stale-PR policy to `CONTRIBUTING.md` so contributors know what to + expect. +- Triage the currently open pull requests: merge or close the oldest, and leave + a comment on each remaining one stating what it needs. -Done when: the policy is published and every open PR has a current status comment. +Done when: the policy is published and every open PR has a current status +comment. ### Name maintainers and route reviews to subject-matter experts -- Add a `MAINTAINERS.md`, or a "Maintainers" section on the Contributing page, that names the user guide approvers and the person or group responsible for the release-notes script, and how to reach them. -- Add per-directory `OWNERS` files (`docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS`) that reference the existing `sig-network-*`, `sig-storage-*`, and `sig-compute-*` aliases, keeping the root approvers for site-wide changes. -- Ask the maintainers to consider a documentation-focused reviewer role or SIG Docs alias so writers who are not code approvers can share the review load. - -Done when: a pull request touching `docs/storage/` requests review from the storage alias. +- Add a `MAINTAINERS.md`, or a "Maintainers" section on the Contributing page, + that names the user guide approvers and the person or group responsible for + the release-notes script, and how to reach them. +- Add per-directory `OWNERS` files (`docs/network/OWNERS`, + `docs/storage/OWNERS`, `docs/compute/OWNERS`) that reference the existing + `sig-network-*`, `sig-storage-*`, and `sig-compute-*` aliases, keeping the + root approvers for site-wide changes. +- Ask the maintainers to consider a documentation-focused reviewer role or SIG + Docs alias so writers who are not code approvers can share the review load. + +Done when: a pull request touching `docs/storage/` requests review from the +storage alias. diff --git a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md index 8c0e63b9..b6dc5616 100644 --- a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md +++ b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md @@ -1,70 +1,111 @@ --- -title: Create a new-user Getting Started path from installation to a running VirtualMachine +title: + Create a new-user Getting Started path from installation to a running + VirtualMachine labels: [urgent, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Overview -A new user who arrives at the user guide cannot follow one path from "I have a cluster" to "I have a running VM." The Installation page buries the four-command install under platform-specific material, the `virtctl` page covers only one binary, Basic Use centers on VirtualMachineInstance rather than VirtualMachine, Lifecycle references a `vmi.yaml` that is never defined, and nothing on the Welcome page tells a newcomer where to start. +A new user who arrives at the user guide cannot follow one path from "I have a +cluster" to "I have a running VM." The Installation page buries the four-command +install under platform-specific material, the `virtctl` page covers only one +binary, Basic Use centers on VirtualMachineInstance rather than VirtualMachine, +Lifecycle references a `vmi.yaml` that is never defined, and nothing on the +Welcome page tells a newcomer where to start. -The sub-issues below add a single Getting Started page and reshape the pages it links to so each one hands the reader to the next. Complete the sub-issues in order where possible; the later ones link to pages created by the earlier ones. +The sub-issues below add a single Getting Started page and reshape the pages it +links to so each one hands the reader to the next. Complete the sub-issues in +order where possible; the later ones link to pages created by the earlier ones. ## Sub-issues ### Add a Getting Started page after Architecture -Create `docs/getting_started.md` and add it to `docs/.nav.yml` immediately after Architecture. On one page, walk a reader from a working cluster to a running VM: +Create `docs/getting_started.md` and add it to `docs/.nav.yml` immediately after +Architecture. On one page, walk a reader from a working cluster to a running VM: 1. Install KubeVirt with the four `kubectl` commands from the Installation page. 2. Install `virtctl`. -3. Create a VirtualMachine from a provided minimal manifest or `virtctl create vm`. +3. Create a VirtualMachine from a provided minimal manifest or + `virtctl create vm`. 4. Start it, connect with `virtctl console`, and stop it. -Link to the detailed page at each step rather than repeating its content. Consider folding the current Quickstarts page into this page as a "Try it in a sandbox" section. +Link to the detailed page at each step rather than repeating its content. +Consider folding the current Quickstarts page into this page as a "Try it in a +sandbox" section. -Done when: a reader can complete the page in under 30 minutes on a fresh cluster and every step links to the page that explains it. +Done when: a reader can complete the page in under 30 minutes on a fresh cluster +and every step links to the page that explains it. ### Point newcomers at the Getting Started page from Welcome and Quickstarts -On the Welcome page (`docs/index.md`), add a one-line "New to KubeVirt? Start here" link at the top that points to the Getting Started page. +On the Welcome page (`docs/index.md`), add a one-line "New to KubeVirt? Start +here" link at the top that points to the Getting Started page. -On the Quickstarts page (`docs/quickstarts.md`), add 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 will have at the end. Add a closing link to the Getting Started page. +On the Quickstarts page (`docs/quickstarts.md`), add 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 +will have at the end. Add a closing link to the Getting Started page. -Done when: both pages link to Getting Started and the Quickstarts page states its prerequisites. +Done when: both pages link to Getting Started and the Quickstarts page states +its prerequisites. ### Rewrite Basic Use as "Your first VirtualMachine" and fix the Lifecycle manifest reference -Rewrite `docs/user_workloads/basic_use.md` into a short page that presents VirtualMachine as the primary object and VirtualMachineInstance as the running instance it manages. Include: +Rewrite `docs/user_workloads/basic_use.md` into a short page that presents +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. -- The `kubectl apply`, `virtctl start`, `virtctl console`, and `virtctl stop` commands. -- Explicit links to the next pages (Creating VirtualMachines, Accessing Virtual Machines, Lifecycle). +- The `kubectl apply`, `virtctl start`, `virtctl console`, and `virtctl stop` + commands. +- Explicit links to the next pages (Creating VirtualMachines, Accessing Virtual + Machines, Lifecycle). -Update `docs/user_workloads/lifecycle.md` to reference that `vm.yaml` manifest instead of the undefined `vmi.yaml`. +Update `docs/user_workloads/lifecycle.md` to reference that `vm.yaml` manifest +instead of the undefined `vmi.yaml`. -Done when: Basic Use and Lifecycle use the same manifest and a reader can run both pages end to end. +Done when: Basic Use and Lifecycle use the same manifest and a reader can run +both pages end to end. ### Restructure the Installation page so the core procedure comes first -Reorder `docs/cluster_admin/installation.md` so the first screen covers Requirements, the four-command operator install, verification, and the emulation fallback. Move the following below a "Platform-specific and advanced installation" heading, or onto separate pages: AppArmor, kernel and user-land compatibility, SELinux, OKD, k3OS, daily developer builds, deploying from source, network plugins, and node placement. +Reorder `docs/cluster_admin/installation.md` so the first screen covers +Requirements, the four-command operator install, verification, and the emulation +fallback. Move the following below a "Platform-specific and advanced +installation" heading, or onto separate pages: AppArmor, kernel and user-land +compatibility, SELinux, OKD, k3OS, daily developer builds, deploying from +source, network plugins, and node placement. -Remove, or move to a footnote, the historical notes about behavior before v0.20.0 and v0.34.2. Ask the maintainers whether any supported upgrade path still requires them. +Remove, or move to a footnote, the historical notes about behavior before +v0.20.0 and v0.34.2. Ask the maintainers whether any supported upgrade path +still requires them. -Done when: the standard install is complete before the first platform-specific heading. +Done when: the standard install is complete before the first platform-specific +heading. ### End the Installation page with a Next steps section -Add a "Next steps" section to the end of `docs/cluster_admin/installation.md` that links to Installing virtctl, Creating VirtualMachines by using virtctl, and Accessing Virtual Machines. +Add a "Next steps" section to the end of `docs/cluster_admin/installation.md` +that links to Installing virtctl, Creating VirtualMachines by using virtctl, and +Accessing Virtual Machines. Done when: the Installation page no longer ends on an advanced topic. ### Expand the virtctl page to cover all client binaries and rename it "Installing virtctl" -Expand `docs/user_workloads/virtctl_client_tool.md` to cover every published client binary. Use the Material theme's content tabs for Linux, macOS, and Windows on both amd64 and arm64, and include the `chmod +x` and `PATH` steps. Rename the page title to "Installing virtctl". Either move the page next to Installation in the navigation or link to it from Installation's Next steps. +Expand `docs/user_workloads/virtctl_client_tool.md` to cover every published +client binary. Use the Material theme's content tabs for Linux, macOS, and +Windows on both amd64 and arm64, and include the `chmod +x` and `PATH` steps. +Rename the page title to "Installing virtctl". Either move the page next to +Installation in the navigation or link to it from Installation's Next steps. -Done when: a user on any supported platform can install `virtctl` from this page alone. +Done when: a user on any supported platform can install `virtctl` from this page +alone. ## Related -The virtctl command reference and the Troubleshooting page are tracked separately; link to them from Getting Started when they exist. +The virtctl command reference and the Troubleshooting page are tracked +separately; link to them from Getting Started when they exist. diff --git a/analyses/2026/kubevirt/issues/U-document-community-channels.md b/analyses/2026/kubevirt/issues/U-document-community-channels.md index 4486945a..a018427c 100644 --- a/analyses/2026/kubevirt/issues/U-document-community-channels.md +++ b/analyses/2026/kubevirt/issues/U-document-community-channels.md @@ -1,45 +1,85 @@ --- -title: Document community channels in the guide and maintain a beginner-friendly issue backlog +title: + Document community channels in the guide and maintain a beginner-friendly + issue backlog labels: [urgent, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Overview -Readers who stay inside the user guide see only a raw Slack URL on the Welcome page; the channels, mailing list, and community meetings are documented on `kubevirt.io/community` but not in the guide. On the contributor side, the repository uses two spellings of the good-first-issue label, so beginner issues do not appear in GitHub's "Contribute" tab, and unlabeled issues reach `lifecycle/rotten` and close without triage. +Readers who stay inside the user guide see only a raw Slack URL on the Welcome +page; the channels, mailing list, and community meetings are documented on +`kubevirt.io/community` but not in the guide. On the contributor side, the +repository uses two spellings of the good-first-issue label, so beginner issues +do not appear in GitHub's "Contribute" tab, and unlabeled issues reach +`lifecycle/rotten` and close without triage. -The sub-issues below bring the community information into the guide and set up the labels, triage habits, and cadence that keep a small pool of beginner issues available. Documentation also needs a formal home in the community SIG list so newcomers know where to volunteer. +The sub-issues below bring the community information into the guide and set up +the labels, triage habits, and cadence that keep a small pool of beginner issues +available. Documentation also needs a formal home in the community SIG list so +newcomers know where to volunteer. ## Sub-issues ### Add a Community and communication page to the guide -Add a page, or a section on the Contributing page, that consolidates the Slack channels, the `kubevirt-dev` mailing list, community meetings, and social accounts in one place. Give each channel a one-line description of its purpose: `#virtualization` for usage questions, `#kubevirt-dev` for contributor discussion, the mailing list for announcements and longer threads. State the meeting cadence and times and include the public calendar link (`kubevirt@cncf.io`). Keep the content consistent with `kubevirt.io/community`. +Add a page, or a section on the Contributing page, that consolidates the Slack +channels, the `kubevirt-dev` mailing list, community meetings, and social +accounts in one place. Give each channel a one-line description of its purpose: +`#virtualization` for usage questions, `#kubevirt-dev` for contributor +discussion, the mailing list for announcements and longer threads. State the +meeting cadence and times and include the public calendar link +(`kubevirt@cncf.io`). Keep the content consistent with `kubevirt.io/community`. -On the Welcome page, replace the raw Slack URL with the channel name and a link to the Kubernetes Slack invitation page. Add a short "Community and adoption" block to `docs/index.md` that links to the `kubevirt.io` blog, videos, Summit, adopters page, and Slack. On `docs/contributing.md`, where readers are invited to submit case studies, link the existing adopters list and CNCF case studies so contributors can see the format they are being asked to follow. +On the Welcome page, replace the raw Slack URL with the channel name and a link +to the Kubernetes Slack invitation page. Add a short "Community and adoption" +block to `docs/index.md` that links to the `kubevirt.io` blog, videos, Summit, +adopters page, and Slack. On `docs/contributing.md`, where readers are invited +to submit case studies, link the existing adopters list and CNCF case studies so +contributors can see the format they are being asked to follow. -Done when: a reader can find every channel and the meeting schedule without leaving the guide. +Done when: a reader can find every channel and the meeting schedule without +leaving the guide. ### Standardize on the `good first issue` label -Standardize on the GitHub-native `good first issue` label (spaced) and retire or alias the hyphenated `good-first-issue`, so beginner issues appear in GitHub's "Contribute" tab and discovery tooling. Relabel existing issues and update the reference on the Contributing page to match. Reference both `good first issue` and `help wanted` on the Contributing page and explain the difference: `help wanted` marks slightly larger but still approachable tasks. +Standardize on the GitHub-native `good first issue` label (spaced) and retire or +alias the hyphenated `good-first-issue`, so beginner issues appear in GitHub's +"Contribute" tab and discovery tooling. Relabel existing issues and update the +reference on the Contributing page to match. Reference both `good first issue` +and `help wanted` on the Contributing page and explain the difference: +`help wanted` marks slightly larger but still approachable tasks. -Done when: only one spelling of the label is in use and the Contributing page explains both labels. +Done when: only one spelling of the label is in use and the Contributing page +explains both labels. ### Triage the open issue backlog -Apply `kind/*` and `sig/documentation` labels to unlabeled open issues, and apply `triage/accepted` to issues that are ready to be worked on. Apply `lifecycle/frozen` to still-relevant enhancements and documentation requests so they do not reach `lifecycle/rotten` and close for inactivity alone. +Apply `kind/*` and `sig/documentation` labels to unlabeled open issues, and +apply `triage/accepted` to issues that are ready to be worked on. Apply +`lifecycle/frozen` to still-relevant enhancements and documentation requests so +they do not reach `lifecycle/rotten` and close for inactivity alone. Done when: every open issue has a `kind/*` label and a triage state. ### Seed and maintain a pool of beginner issues -Identify documentation gaps, typos, and small feature-doc updates and file them as `good first issue`, aiming for five to ten open at any time. Add a short "good first issue" checklist to the issue templates (affected page, expected outcome, pointers to relevant docs) so each beginner issue is self-contained. +Identify documentation gaps, typos, and small feature-doc updates and file them +as `good first issue`, aiming for five to ten open at any time. Add a short +"good first issue" checklist to the issue templates (affected page, expected +outcome, pointers to relevant docs) so each beginner issue is self-contained. -Done when: at least five `good first issue` items are open and each follows the checklist. +Done when: at least five `good first issue` items are open and each follows the +checklist. ### Publish a documentation triage cadence and give documentation a SIG home -Publish a lightweight triage cadence, for example a periodic documentation-issue triage during a SIG or community meeting, so labeling, acceptance, and staleness decisions stay consistent. Populate the `sig/documentation` entry in the community `sig-list.md` with chairs, a meeting cadence or async channel, and a charter that covers both the user guide and the website. +Publish a lightweight triage cadence, for example a periodic documentation-issue +triage during a SIG or community meeting, so labeling, acceptance, and staleness +decisions stay consistent. Populate the `sig/documentation` entry in the +community `sig-list.md` with chairs, a meeting cadence or async channel, and a +charter that covers both the user guide and the website. -Done when: the cadence is written down on the Contributing page and `sig-list.md` has a complete documentation entry. +Done when: the cadence is written down on the Contributing page and +`sig-list.md` has a complete documentation entry. diff --git a/analyses/2026/kubevirt/issues/U-document-site-ownership.md b/analyses/2026/kubevirt/issues/U-document-site-ownership.md index 350997ab..0a1ee3a0 100644 --- a/analyses/2026/kubevirt/issues/U-document-site-ownership.md +++ b/analyses/2026/kubevirt/issues/U-document-site-ownership.md @@ -1,55 +1,95 @@ --- -title: Document site infrastructure ownership and the boundary between documentation sources +title: + Document site infrastructure ownership and the boundary between documentation + sources labels: [high, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Overview -Nobody can tell from the repositories who administers the Netlify site, DNS, GitHub Pages, analytics, or the Prow jobs, or how to become a user guide approver. User-facing content is also spread across three places: this guide, `kubevirt/kubevirt/docs`, and the CDI `doc/` directory, with no statement of which content belongs where. +Nobody can tell from the repositories who administers the Netlify site, DNS, +GitHub Pages, analytics, or the Prow jobs, or how to become a user guide +approver. User-facing content is also spread across three places: this guide, +`kubevirt/kubevirt/docs`, and the CDI `doc/` directory, with no statement of +which content belongs where. -The sub-issues below write down infrastructure ownership and the maintainer ladder so the sites survive maintainer turnover, and define and enforce a content boundary so users find documentation in one place. +The sub-issues below write down infrastructure ownership and the maintainer +ladder so the sites survive maintainer turnover, and define and enforce a +content boundary so users find documentation in one place. ## Sub-issues ### Add a Site infrastructure section to the README -Add a "Site infrastructure" section to the README of `kubevirt/user-guide` (and propose the same for `kubevirt/kubevirt.github.io`, or a page in `kubevirt/community`) that lists who administers the Netlify site, GitHub Pages and custom-domain settings, DNS for `kubevirt.io`, the analytics and Search Console accounts, and the Prow job definitions in `kubevirt/project-infra`, and how a maintainer requests access or a 404 report. +Add a "Site infrastructure" section to the README of `kubevirt/user-guide` (and +propose the same for `kubevirt/kubevirt.github.io`, or a page in +`kubevirt/community`) that lists who administers the Netlify site, GitHub Pages +and custom-domain settings, DNS for `kubevirt.io`, the analytics and Search +Console accounts, and the Prow job definitions in `kubevirt/project-infra`, and +how a maintainer requests access or a 404 report. Done when: every piece of infrastructure names an owner and an access path. ### Publish a maintainer ladder and keep OWNERS_ALIASES current -In the README, describe how a contributor becomes a reviewer and then an approver (for example, a number of merged docs PRs and a nomination), mirroring the process in `kubevirt/community` for code SIGs. Review `OWNERS_ALIASES` and add dated emeritus entries for inactive approvers, as the website repository already does. +In the README, describe how a contributor becomes a reviewer and then an +approver (for example, a number of merged docs PRs and a nomination), mirroring +the process in `kubevirt/community` for code SIGs. Review `OWNERS_ALIASES` and +add dated emeritus entries for inactive approvers, as the website repository +already does. -Done when: the ladder is published and `OWNERS_ALIASES` lists only active approvers plus dated emeritus entries. +Done when: the ladder is published and `OWNERS_ALIASES` lists only active +approvers plus dated emeritus entries. ### Add a Strict-Transport-Security header or record the gap -GitHub Pages does not let you set response headers directly. Either enable HSTS through the DNS or CDN provider in front of `kubevirt.io`, or record the limitation in the Site infrastructure section so it is a known gap. For the user guide on Netlify, add the header in `netlify.toml`. +GitHub Pages does not let you set response headers directly. Either enable HSTS +through the DNS or CDN provider in front of `kubevirt.io`, or record the +limitation in the Site infrastructure section so it is a known gap. For the user +guide on Netlify, add the header in `netlify.toml`. -Done when: `curl -I https://kubevirt.io/user-guide/` returns `Strict-Transport-Security`, and the main site's status is recorded. +Done when: `curl -I https://kubevirt.io/user-guide/` returns +`Strict-Transport-Security`, and the main site's status is recorded. ### Document where documentation lives -Add a short "Where documentation lives" section to the README of `kubevirt/user-guide`, and propose the same text for `kubevirt/kubevirt.github.io` and `kubevirt/kubevirt`, stating that user and operator documentation belongs in the user guide, marketing, blog, and community content belongs on the website, and `kubevirt/kubevirt/docs` is for design and developer notes only. Link to it from `docs/contributing.md`. +Add a short "Where documentation lives" section to the README of +`kubevirt/user-guide`, and propose the same text for +`kubevirt/kubevirt.github.io` and `kubevirt/kubevirt`, stating that user and +operator documentation belongs in the user guide, marketing, blog, and community +content belongs on the website, and `kubevirt/kubevirt/docs` is for design and +developer notes only. Link to it from `docs/contributing.md`. Done when: all three repositories state the same boundary. ### Record the repository and toolchain decisions -Decide whether the website and user guide should share a repository, and record the decision in both READMEs with the reason (for example, different generators, maintainers, and audiences). Open a tracking issue to evaluate converging the two toolchains on Material for MkDocs or another generator with a supported theme, so a single skill set covers both sites, even if the migration is deferred. +Decide whether the website and user guide should share a repository, and record +the decision in both READMEs with the reason (for example, different generators, +maintainers, and audiences). Open a tracking issue to evaluate converging the +two toolchains on Material for MkDocs or another generator with a supported +theme, so a single skill set covers both sites, even if the migration is +deferred. Done when: both decisions are written down with an owner and a revisit date. ### Move user-facing content out of kubevirt/kubevirt/docs -Audit `kubevirt/kubevirt/docs` for user-facing content, starting with the files the user guide already links to (`getting-started.md`, `architecture.md`, `cloud-init.md`). Move the user-facing portions into the guide and replace the originals with a one-line pointer so search results and old links still resolve. +Audit `kubevirt/kubevirt/docs` for user-facing content, starting with the files +the user guide already links to (`getting-started.md`, `architecture.md`, +`cloud-init.md`). Move the user-facing portions into the guide and replace the +originals with a one-line pointer so search results and old links still resolve. -Done when: the guide no longer links to `kubevirt/kubevirt/docs` for user-facing content. +Done when: the guide no longer links to `kubevirt/kubevirt/docs` for user-facing +content. ### Triage the CDI documentation the guide links to -Six storage pages link to the CDI `doc/` directory. Either move those pages into the guide's `storage/` section, or add a "CDI reference documentation" page in the guide that explains why the rest remains in the CDI repository and links to it. +Six storage pages link to the CDI `doc/` directory. Either move those pages into +the guide's `storage/` section, or add a "CDI reference documentation" page in +the guide that explains why the rest remains in the CDI repository and links to +it. -Done when: every CDI link from the guide goes through a page that explains the boundary. +Done when: every CDI link from the guide goes through a page that explains the +boundary. diff --git a/analyses/2026/kubevirt/issues/U-document-v19-features.md b/analyses/2026/kubevirt/issues/U-document-v19-features.md index 47557d93..9fb4e176 100644 --- a/analyses/2026/kubevirt/issues/U-document-v19-features.md +++ b/analyses/2026/kubevirt/issues/U-document-v19-features.md @@ -6,45 +6,73 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -Several features shipped in KubeVirt v1.9 appear only in the release notes, so users cannot find how to use them. The guide also lacks two reference pages that readers expect: a list of feature gates with their stage and version, and a list of `virtctl` subcommands. Feature pages that do state a stage use an informal `FEATURE STATE:` block whose format varies. +Several features shipped in KubeVirt v1.9 appear only in the release notes, so +users cannot find how to use them. The guide also lacks two reference pages that +readers expect: a list of feature gates with their stage and version, and a list +of `virtctl` subcommands. Feature pages that do state a stage use an informal +`FEATURE STATE:` block whose format varies. -The sub-issues below add the missing feature documentation, create the two reference pages, and standardize the feature-state banner so future pages follow one pattern. +The sub-issues below add the missing feature documentation, create the two +reference pages, and standardize the feature-state banner so future pages follow +one pattern. ## Sub-issues ### Document the VirtualMachineBackup API -Add a page under `docs/storage/` that explains the `VirtualMachineBackup` API introduced in v1.9: what it backs up, the required feature gate, a minimal manifest, how to check status, and how it relates to the snapshot and export features. Add it to `docs/storage/.nav.yml` and link it from the release notes entry. +Add a page under `docs/storage/` that explains the `VirtualMachineBackup` API +introduced in v1.9: what it backs up, the required feature gate, a minimal +manifest, how to check status, and how it relates to the snapshot and export +features. Add it to `docs/storage/.nav.yml` and link it from the release notes +entry. Done when: a user can create and verify a backup by following the page. ### Document the CrossArchitectureVirtualization feature gate -Add a section or page, under `docs/compute/` or `docs/cluster_admin/`, for the `CrossArchitectureVirtualization` feature gate: what it enables, the supported architecture combinations, how to enable it, and known limitations. Link it from the Arm64 pages where relevant. +Add a section or page, under `docs/compute/` or `docs/cluster_admin/`, for the +`CrossArchitectureVirtualization` feature gate: what it enables, the supported +architecture combinations, how to enable it, and known limitations. Link it from +the Arm64 pages where relevant. Done when: the gate is documented somewhere other than the release notes. ### Document masquerade PortRanges and MigrationPolicy compression -- In Interfaces and Networks (`docs/network/interfaces_and_networks.md`), add a subsection on masquerade `PortRanges` with a manifest example. -- In Migration Policies (`docs/cluster_admin/migration_policies.md`), add a subsection on MigrationPolicy compression with a manifest example and guidance on when to enable it. +- In Interfaces and Networks (`docs/network/interfaces_and_networks.md`), add a + subsection on masquerade `PortRanges` with a manifest example. +- In Migration Policies (`docs/cluster_admin/migration_policies.md`), add a + subsection on MigrationPolicy compression with a manifest example and guidance + on when to enable it. Done when: both features are documented on the page where users configure them. ### Create a virtctl command reference -Create a `virtctl` command reference page, or expand `docs/user_workloads/virtctl_client_tool.md` beyond installation, that lists each subcommand with a one-line description and a link to the feature page that explains it in context. Generate the subcommand list from `virtctl --help` for the current release so it is complete. +Create a `virtctl` command reference page, or expand +`docs/user_workloads/virtctl_client_tool.md` beyond installation, that lists +each subcommand with a one-line description and a link to the feature page that +explains it in context. Generate the subcommand list from `virtctl --help` for +the current release so it is complete. Done when: every `virtctl` subcommand appears with a description and a link. ### Add a feature-gate table to the feature gates page -On Activating and Deactivating Feature Gates (`docs/cluster_admin/activating_feature_gates.md`), add a table that lists each feature gate, its stage (Alpha, Beta, GA, Deprecated), the version it was introduced or graduated, and a link to its documentation. Ask the maintainers whether this table can be generated from the `kubevirt/kubevirt` source to avoid drift; if so, document the generation step. +On Activating and Deactivating Feature Gates +(`docs/cluster_admin/activating_feature_gates.md`), add a table that lists each +feature gate, its stage (Alpha, Beta, GA, Deprecated), the version it was +introduced or graduated, and a link to its documentation. Ask the maintainers +whether this table can be generated from the `kubevirt/kubevirt` source to avoid +drift; if so, document the generation step. Done when: every feature gate in the current release appears in the table. ### Standardize the feature-state admonition and apply it to every feature page -Define a standard feature-state admonition that states the version introduced and the current stage (Alpha, Beta, GA, Deprecated). Document its format in `CONTRIBUTING.md`. Replace the existing `FEATURE STATE:` blocks on the pages that have them and add the admonition to feature pages that have none. +Define a standard feature-state admonition that states the version introduced +and the current stage (Alpha, Beta, GA, Deprecated). Document its format in +`CONTRIBUTING.md`. Replace the existing `FEATURE STATE:` blocks on the pages +that have them and add the admonition to feature pages that have none. Done when: every feature page opens with the same admonition format. diff --git a/analyses/2026/kubevirt/issues/U-enable-analytics.md b/analyses/2026/kubevirt/issues/U-enable-analytics.md index 1ad2d7c3..a5365a95 100644 --- a/analyses/2026/kubevirt/issues/U-enable-analytics.md +++ b/analyses/2026/kubevirt/issues/U-enable-analytics.md @@ -6,24 +6,39 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -The user guide collects no analytics, so maintainers cannot see which pages are read, what users search for, or which URLs return 404. The main site has an Adobe Analytics tag, but it also fires on preview deploys, which pollutes the data. The sub-issues below add analytics to the guide, restrict it to production, and set up the one report that pays for itself: a list of 404 hits to feed the `redirects` map in `mkdocs.yml`. +The user guide collects no analytics, so maintainers cannot see which pages are +read, what users search for, or which URLs return 404. The main site has an +Adobe Analytics tag, but it also fires on preview deploys, which pollutes the +data. The sub-issues below add analytics to the guide, restrict it to +production, and set up the one report that pays for itself: a list of 404 hits +to feed the `redirects` map in `mkdocs.yml`. ## Sub-issues ### Enable analytics on the user guide -Add an `extra.analytics` block to `mkdocs.yml`. The Material theme supports Google Analytics 4 natively; alternatively, add a custom `overrides/main.html` partial that loads the same Adobe Analytics tag the main site uses so both properties report to one place. Confirm with the website maintainers which property to use. +Add an `extra.analytics` block to `mkdocs.yml`. The Material theme supports +Google Analytics 4 natively; alternatively, add a custom `overrides/main.html` +partial that loads the same Adobe Analytics tag the main site uses so both +properties report to one place. Confirm with the website maintainers which +property to use. -Done when: page views from `kubevirt.io/user-guide` appear in the chosen analytics property. +Done when: page views from `kubevirt.io/user-guide` appear in the chosen +analytics property. ### Load analytics only in production -Inject the analytics snippet only when the Netlify `CONTEXT` variable equals `production`, for example by templating it in the `netlify.toml` build command or by reading an environment variable in the override partial. +Inject the analytics snippet only when the Netlify `CONTEXT` variable equals +`production`, for example by templating it in the `netlify.toml` build command +or by reading an environment variable in the override partial. Done when: a deploy preview loads no analytics script. ### Set up a recurring 404 report and feed it into the redirects map -Once analytics are live, create a saved report filtered on the not-found page title, review it on a regular cadence, and add missing entries to the `redirects` plugin map in `mkdocs.yml`. Document the cadence and the report location in the README's site infrastructure section. +Once analytics are live, create a saved report filtered on the not-found page +title, review it on a regular cadence, and add missing entries to the +`redirects` plugin map in `mkdocs.yml`. Document the cadence and the report +location in the README's site infrastructure section. Done when: the report exists and the first batch of redirects from it is merged. diff --git a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md index e6534822..0eea2aeb 100644 --- a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md +++ b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md @@ -6,73 +6,116 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -The documentation analysis covered the main `kubevirt.io` website as well as the user guide, and found gaps on the website that affect documentation users: the copyright line is missing its © symbol, `robots.txt` points at the wrong sitemap and omits the user guide's, the site search indexes only blog posts, there is no root `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md`, two published CNCF case studies are not linked anywhere, and the adopter use cases in `ADOPTERS.md` never reach the site. - -All changes in this issue land in the `kubevirt/kubevirt.github.io` repository. The issue is filed here so the documentation work is tracked in one place; transfer it if the maintainers prefer. +The documentation analysis covered the main `kubevirt.io` website as well as the +user guide, and found gaps on the website that affect documentation users: the +copyright line is missing its © symbol, `robots.txt` points at the wrong sitemap +and omits the user guide's, the site search indexes only blog posts, there is no +root `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md`, two published CNCF case studies +are not linked anywhere, and the adopter use cases in `ADOPTERS.md` never reach +the site. + +All changes in this issue land in the `kubevirt/kubevirt.github.io` repository. +The issue is filed here so the documentation work is tracked in one place; +transfer it if the maintainers prefer. ## Sub-issues ### Add the © symbol and the missing root repository files -- In `_includes/footer.html`, change the copyright line to read "Copyright © KubeVirt a Series of LF Projects, LLC". -- Add a root `CONTRIBUTING.md` that points to the existing contributing content in the README and to the user guide's Contributing page. -- Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of conduct. -- Add a note to the README naming the file to edit when the CNCF maturity statement changes. +- In `_includes/footer.html`, change the copyright line to read "Copyright © + KubeVirt a Series of LF Projects, LLC". +- Add a root `CONTRIBUTING.md` that points to the existing contributing content + in the README and to the user guide's Contributing page. +- Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of + conduct. +- Add a note to the README naming the file to edit when the CNCF maturity + statement changes. Done when: the footer shows ©, and both files exist at the repository root. ### Fix robots.txt, gate analytics to production, and block indexing of previews -- In `robots.txt`, correct the sitemap URL to `https://kubevirt.io/sitemap.xml` and add a second `Sitemap:` line for `https://kubevirt.io/user-guide/sitemap.xml`. -- In `_includes/head.html`, wrap the `dpal.js` Adobe Analytics include in a check on `jekyll.environment == "production"`, and set `JEKYLL_ENV=production` only in the Netlify production context. -- Emit `X-Robots-Tag: noindex` for deploy previews and branch deploys from a `_headers` file or `netlify.toml` context section. +- In `robots.txt`, correct the sitemap URL to `https://kubevirt.io/sitemap.xml` + and add a second `Sitemap:` line for + `https://kubevirt.io/user-guide/sitemap.xml`. +- In `_includes/head.html`, wrap the `dpal.js` Adobe Analytics include in a + check on `jekyll.environment == "production"`, and set `JEKYLL_ENV=production` + only in the Netlify production context. +- Emit `X-Robots-Tag: noindex` for deploy previews and branch deploys from a + `_headers` file or `netlify.toml` context section. -Done when: `robots.txt` lists both sitemaps, previews send no analytics, and previews return the `noindex` header. +Done when: `robots.txt` lists both sitemaps, previews send no analytics, and +previews return the `noindex` header. ### Link the existing CNCF case studies from the landing page -Add a "Case Studies" block beneath the End Users logo wall on the landing page that links the two published CNCF case studies (NTT Docomo Business and Swisscom). The content already exists; this is a quick win. +Add a "Case Studies" block beneath the End Users logo wall on the landing page +that links the two published CNCF case studies (NTT Docomo Business and +Swisscom). The content already exists; this is a quick win. Done when: both case studies are reachable from the landing page. ### Show adopter use cases on the logo wall -Extend `adopters.py` and `_data/adopters.yml` to carry the "Use-Case" text from `ADOPTERS.md`, and show it as a tooltip or an expandable card on each logo. This turns the logo wall into short, attributed testimonials at no authoring cost. +Extend `adopters.py` and `_data/adopters.yml` to carry the "Use-Case" text from +`ADOPTERS.md`, and show it as a tooltip or an expandable card on each logo. This +turns the logo wall into short, attributed testimonials at no authoring cost. Done when: hovering or expanding a logo shows that adopter's use case. ### Create an adopters page -Create a `/adopters/` or `/case-studies/` page that renders the full adopters table (type, name, since, use case) and links to the CNCF case studies, so evaluators have a single place for adoption evidence. Add it to `_data/site_nav_pages.yml`. +Create a `/adopters/` or `/case-studies/` page that renders the full adopters +table (type, name, since, use case) and links to the CNCF case studies, so +evaluators have a single place for adoption evidence. Add it to +`_data/site_nav_pages.yml`. Done when: the page is in the site navigation and lists every adopter. ### Add a Governance section to the Community page -Add a "Governance" section to the Community page that states in two or three sentences how KubeVirt is governed (CNCF incubating project, maintainer group, SIGs and working groups, lazy consensus with maintainer votes) and links `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in `kubevirt/community`. +Add a "Governance" section to the Community page that states in two or three +sentences how KubeVirt is governed (CNCF incubating project, maintainer group, +SIGs and working groups, lazy consensus with maintainer votes) and links +`GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in +`kubevirt/community`. Done when: a visitor can find the governance documents from the Community page. ### Index non-blog pages in site search and cross-link the two searches -Extend the lunr index in `_layouts/search.html` to include `site.pages` in addition to `site.posts`, so non-blog pages are searchable. Add a link from the main site's search page to the user guide search, and from the user guide's search results to the main site's, so users can find documentation from either entry point. +Extend the lunr index in `_layouts/search.html` to include `site.pages` in +addition to `site.posts`, so non-blog pages are searchable. Add a link from the +main site's search page to the user guide search, and from the user guide's +search results to the main site's, so users can find documentation from either +entry point. -Done when: a search for "installation" on `kubevirt.io` returns the relevant page. +Done when: a search for "installation" on `kubevirt.io` returns the relevant +page. ### Add blog categories beyond news and uncategorized -Add a category or tag scheme (for example release, feature, community, user story) and backfill recent posts, so the blog index can filter by type and adopter stories can be listed together. +Add a category or tag scheme (for example release, feature, community, user +story) and backfill recent posts, so the blog index can filter by type and +adopter stories can be listed together. Done when: the blog index offers category filtering and recent posts are tagged. ### Point vendor logos at KubeVirt-specific pages -For each entry in `ADOPTERS.md` whose link is a corporate homepage, ask the vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, and update the link. Drop the logo from the Vendors section if no such page exists. +For each entry in `ADOPTERS.md` whose link is a corporate homepage, ask the +vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, +and update the link. Drop the logo from the Vendors section if no such page +exists. Done when: every vendor logo links to a page that mentions KubeVirt. ### Publish a short brand reference -Publish a brand reference, in this repository or in `kubevirt/community`, that lists the canonical logo files (icon and horizontal wordmark), the hex values of the `$kv-color--green-*` scale, and the approved typefaces. Have `docs/stylesheets/extra.css` in the user guide cite that reference in a comment so the two sites stay aligned when the palette changes. +Publish a brand reference, in this repository or in `kubevirt/community`, that +lists the canonical logo files (icon and horizontal wordmark), the hex values of +the `$kv-color--green-*` scale, and the approved typefaces. Have +`docs/stylesheets/extra.css` in the user guide cite that reference in a comment +so the two sites stay aligned when the palette changes. Done when: both repositories point at the same brand reference. diff --git a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md index 8f9fe193..48703c75 100644 --- a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md +++ b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md @@ -1,40 +1,63 @@ --- -title: Fix navigation gaps and reorganize the user guide information architecture +title: + Fix navigation gaps and reorganize the user guide information architecture labels: [urgent, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Overview -Several pages are unreachable or misplaced in the navigation, and page titles in the Storage section describe APIs rather than what a reader accomplishes. The Plugins page is reachable only from the deprecated Hook Sidecar page, a byte-identical duplicate of the Windows virtio drivers page is unlisted, Release Notes sits in the middle of the main navigation, and the API reference has no home in the guide. +Several pages are unreachable or misplaced in the navigation, and page titles in +the Storage section describe APIs rather than what a reader accomplishes. The +Plugins page is reachable only from the deprecated Hook Sidecar page, a +byte-identical duplicate of the Windows virtio drivers page is unlisted, Release +Notes sits in the middle of the main navigation, and the API reference has no +home in the guide. -The sub-issues below fix the gaps first and then make the structure read as a progression from concepts through administration, workloads, and infrastructure layers. Every subdirectory under `docs/` has a `.nav.yml` that controls page order; when a file name changes, add a redirect in `mkdocs.yml`. +The sub-issues below fix the gaps first and then make the structure read as a +progression from concepts through administration, workloads, and infrastructure +layers. Every subdirectory under `docs/` has a `.nav.yml` that controls page +order; when a file name changes, add a redirect in `mkdocs.yml`. ## Sub-issues ### Add the Plugins page to the navigation and delete the duplicate Windows virtio drivers page -Add `plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is discoverable from somewhere other than the deprecated Hook Sidecar page. +Add `plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is +discoverable from somewhere other than the deprecated Hook Sidecar page. -Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Add a redirect in `mkdocs.yml` if the old URL was ever published. +Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical +unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Add a +redirect in `mkdocs.yml` if the old URL was ever published. -Done when: Plugins appears in the Cluster Administration navigation and only one Windows virtio drivers page exists. +Done when: Plugins appears in the Cluster Administration navigation and only one +Windows virtio drivers page exists. ### Move Release Notes out of the middle of the main navigation -In `docs/.nav.yml`, move Release Notes to the end of the list or into a top-bar link, so the section list reads Welcome, Architecture, Getting Started, Cluster Administration, User Workloads, Compute, Network, Storage, then Contributing, Release Notes, and Virtualization Debugging. +In `docs/.nav.yml`, move Release Notes to the end of the list or into a top-bar +link, so the section list reads Welcome, Architecture, Getting Started, Cluster +Administration, User Workloads, Compute, Network, Storage, then Contributing, +Release Notes, and Virtualization Debugging. -Done when: the main navigation reads as a progression without the Release Notes interruption. +Done when: the main navigation reads as a progression without the Release Notes +interruption. ### Group legacy workload mechanisms under a Legacy heading -In `docs/user_workloads/.nav.yml`, reorganize the Workloads sub-group so current mechanisms (instance types, VirtualMachine Templates, pools) come first and legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) sit under a clearly labeled "Legacy" heading or at the end. +In `docs/user_workloads/.nav.yml`, reorganize the Workloads sub-group so current +mechanisms (instance types, VirtualMachine Templates, pools) come first and +legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) sit +under a clearly labeled "Legacy" heading or at the end. Done when: a reader sees the recommended mechanism before any deprecated one. ### Add a landing page to each of the Compute, Network, and Storage sections -Add a brief `index.md` landing page to `docs/compute/`, `docs/network/`, and `docs/storage/` that explains what the section covers and groups its pages by task. For example, Storage: provisioning disks, importing images, snapshots and backup, moving data between clusters. Add each landing page to its `.nav.yml`. +Add a brief `index.md` landing page to `docs/compute/`, `docs/network/`, and +`docs/storage/` that explains what the section covers and groups its pages by +task. For example, Storage: provisioning disks, importing images, snapshots and +backup, moving data between clusters. Add each landing page to its `.nav.yml`. Done when: each section opens on a page that orients the reader. @@ -45,20 +68,28 @@ Rename page titles so they state what the reader accomplishes, for example: - "Clone API" to "Cloning VirtualMachines" - "Export API" to "Exporting VirtualMachines and volumes" - "Snapshot Restore API" to "Snapshotting and restoring VirtualMachines" -- "Migration Controller" to a title that states what the reader accomplishes with it +- "Migration Controller" to a title that states what the reader accomplishes + with it -Change titles in the page front matter and `.nav.yml` first. If you also rename files, add redirects in `mkdocs.yml`. +Change titles in the page front matter and `.nav.yml` first. If you also rename +files, add redirects in `mkdocs.yml`. Done when: no Storage page title ends in "API". ### Give the API reference a visible home in the user guide -Add a navigation entry or a short landing page that links to the API reference at `https://kubevirt.io/api-reference/`, so readers do not need to know it is published from a separate repository. +Add a navigation entry or a short landing page that links to the API reference +at `https://kubevirt.io/api-reference/`, so readers do not need to know it is +published from a separate repository. Done when: a reader can reach the API reference from the guide's navigation. ### Remove or archive legacy installation content -Verify with the maintainers whether the OKD Service Catalog APB and k3OS installation paths on `docs/cluster_admin/installation.md` are still supported. Remove the paths that are not, and update the OpenShift 4.10 documentation links to a current version or a version-independent URL. +Verify with the maintainers whether the OKD Service Catalog APB and k3OS +installation paths on `docs/cluster_admin/installation.md` are still supported. +Remove the paths that are not, and update the OpenShift 4.10 documentation links +to a current version or a version-independent URL. -Done when: the Installation page references only supported platforms and current links. +Done when: the Installation page references only supported platforms and current +links. diff --git a/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md b/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md index 5f3f860d..659c5cea 100644 --- a/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md +++ b/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md @@ -6,45 +6,71 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -The guide links to the API reference at `/master/` paths fourteen times, uses `master` as an example node name, and relies on minimizing words such as "simply", "just", and "easily" that tell a struggling reader the task should have been easy. Fixing the links and example is quick. Rewording the prose is a page-by-page pass, and an automated check keeps new occurrences out. +The guide links to the API reference at `/master/` paths fourteen times, uses +`master` as an example node name, and relies on minimizing words such as +"simply", "just", and "easily" that tell a struggling reader the task should +have been easy. Fixing the links and example is quick. Rewording the prose is a +page-by-page pass, and an automated check keeps new occurrences out. -The style-guide rule that discourages minimizing language is tracked in the contributor guide issue. +The style-guide rule that discourages minimizing language is tracked in the +contributor guide issue. ## Sub-issues ### Update legacy branch-name links and the Presets example -- Update the 14 links to `kubevirt.io/api-reference/master/...` to the `/main/` path, or to a specific version path such as `/v1.9.0/`. -- On the Presets page (`docs/user_workloads/presets.md`), replace the `kubevirt.io/nodeName: master` example with a neutral node name such as `node01`, or remove the example, since the page documents a deprecated feature. +- Update the 14 links to `kubevirt.io/api-reference/master/...` to the `/main/` + path, or to a specific version path such as `/v1.9.0/`. +- On the Presets page (`docs/user_workloads/presets.md`), replace the + `kubevirt.io/nodeName: master` example with a neutral node name such as + `node01`, or remove the example, since the page documents a deprecated + feature. -Done when: `grep -r "api-reference/master" docs/` returns nothing and the Presets page uses a neutral node name. +Done when: `grep -r "api-reference/master" docs/` returns nothing and the +Presets page uses a neutral node name. ### Reword minimizing language on the five pages with the most occurrences -On Live Migration, Windows Virtio Drivers, Node Assignment, vsock, and Disks and Volumes, delete "simply", "just", "of course", and "obviously" where they add nothing, and replace "easy" or "easily" with a concrete statement of what the step requires. For example, change "can be easily cancelled" to "can be cancelled by deleting the migration object". +On Live Migration, Windows Virtio Drivers, Node Assignment, vsock, and Disks and +Volumes, delete "simply", "just", "of course", and "obviously" where they add +nothing, and replace "easy" or "easily" with a concrete statement of what the +step requires. For example, change "can be easily cancelled" to "can be +cancelled by deleting the migration object". -Done when: none of the five pages contains the listed words in a minimizing sense. +Done when: none of the five pages contains the listed words in a minimizing +sense. ### Reword minimizing language across the remaining pages -Apply the same pass to the rest of `docs/`. Use `grep -rniw "simply\|just\|easy\|easily\|obviously\|of course" docs/` to find occurrences and review each in context; some uses of "just" are legitimate. +Apply the same pass to the rest of `docs/`. Use +`grep -rniw "simply\|just\|easy\|easily\|obviously\|of course" docs/` to find +occurrences and review each in context; some uses of "just" are legitimate. Done when: the grep returns only legitimate uses. ### Prefer "cancel" over "abort" in Live Migration prose -On the Live Migration page (`docs/compute/live_migration.md`), use "cancel" in the prose while continuing to show the `Abort Requested` and `Abort Status` field names as they appear in `kubectl` output. Ask the KubeVirt API maintainers whether those VirtualMachineInstanceMigration status fields are candidates for a "cancel" alias in a future API version, and record the answer in the issue. +On the Live Migration page (`docs/compute/live_migration.md`), use "cancel" in +the prose while continuing to show the `Abort Requested` and `Abort Status` +field names as they appear in `kubectl` output. Ask the KubeVirt API maintainers +whether those VirtualMachineInstanceMigration status fields are candidates for a +"cancel" alias in a future API version, and record the answer in the issue. Done when: the prose says "cancel" and field names are shown in code formatting. ### Add an automated check for minimizing language -Add a check to the Makefile and the Prow pre-submit, alongside `make check_spelling`, that flags minimizing and non-recommended language in pull requests. Use Vale with the `write-good` style or a grep-based check. +Add a check to the Makefile and the Prow pre-submit, alongside +`make check_spelling`, that flags minimizing and non-recommended language in +pull requests. Use Vale with the `write-good` style or a grep-based check. Done when: a pull request that adds "simply" fails the check. ### Use tagged or permalink URLs for upstream project links -Where the guide links to libvirt, cri-tools, vhost-md, or kubevirt-ansible files on a `master` branch, change the links to a tag or commit permalink so the branch name is not repeated in the guide and the link survives a default-branch rename. +Where the guide links to libvirt, cri-tools, vhost-md, or kubevirt-ansible files +on a `master` branch, change the links to a tag or commit permalink so the +branch name is not repeated in the guide and the link survives a default-branch +rename. Done when: no outbound link in `docs/` includes `/master/`. diff --git a/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md b/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md index 689b5996..a44cc300 100644 --- a/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md +++ b/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md @@ -6,7 +6,12 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -Several one-line configuration changes in `mkdocs.yml` and `netlify.toml` would noticeably improve the guide: copyable code blocks, better search, social links in the header and footer, correct logo alt text, reproducible builds, and no indexing of preview deploys. None requires content changes. Each sub-issue is a single pull request of configuration edits plus a local build (`mkdocs serve`) to confirm the result. +Several one-line configuration changes in `mkdocs.yml` and `netlify.toml` would +noticeably improve the guide: copyable code blocks, better search, social links +in the header and footer, correct logo alt text, reproducible builds, and no +indexing of preview deploys. None requires content changes. Each sub-issue is a +single pull request of configuration edits plus a local build (`mkdocs serve`) +to confirm the result. ## Sub-issues @@ -15,28 +20,44 @@ Several one-line configuration changes in `mkdocs.yml` and `netlify.toml` would Under `theme.features` in `mkdocs.yml`, add: - `content.code.copy`, which adds a copy button to every code block. -- `search.suggest`, `search.highlight`, and `search.share`, which improve search usability. +- `search.suggest`, `search.highlight`, and `search.share`, which improve search + usability. -Done when: a copy button appears on code blocks and search shows suggestions and highlights terms. +Done when: a copy button appears on code blocks and search shows suggestions and +highlights terms. ### Add repository and social links to every page -In `mkdocs.yml`, set `repo_url` to the `kubevirt/user-guide` repository and add an `extra.social` block with the project's GitHub, Slack, mailing list, and `kubevirt.io` links. These appear in the header and footer on every page instead of only in the "Getting help" list on the Welcome page. +In `mkdocs.yml`, set `repo_url` to the `kubevirt/user-guide` repository and add +an `extra.social` block with the project's GitHub, Slack, mailing list, and +`kubevirt.io` links. These appear in the header and footer on every page instead +of only in the "Getting help" list on the Welcome page. -Done when: the header shows the repository link and the footer shows the social icons. +Done when: the header shows the repository link and the footer shows the social +icons. ### Set the logo alt text and remove unused configuration and assets -- Set the logo alt text to "KubeVirt" by adding `extra.homepage` or a custom `overrides/partials/logo.html`. -- Remove the unsupported top-level `site_favicon` key from `mkdocs.yml`; MkDocs ignores it and the active favicon is already set under `theme.favicon`. -- Remove the unused legacy assets `asciibinder-logo-horizontal.png`, `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. +- Set the logo alt text to "KubeVirt" by adding `extra.homepage` or a custom + `overrides/partials/logo.html`. +- Remove the unsupported top-level `site_favicon` key from `mkdocs.yml`; MkDocs + ignores it and the active favicon is already set under `theme.favicon`. +- Remove the unused legacy assets `asciibinder-logo-horizontal.png`, + `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. -Done when: the logo has alt text, `mkdocs build --strict` reports no unknown keys, and `docs/assets` contains only current brand assets. +Done when: the logo has alt text, `mkdocs build --strict` reports no unknown +keys, and `docs/assets` contains only current brand assets. ### Make preview builds reproducible and non-indexable -- Pin the MkDocs package versions in `netlify.toml`, or add a `requirements.txt`, so preview builds match the Prow image. -- Remove the obsolete `sed` line in `netlify.toml` that rewrites `site_url: https://kubevirt.io/docs`; `mkdocs.yml` already sets `site_url` to `https://kubevirt.io/user-guide`. -- Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file or a `[context.deploy-preview]` and `[context.branch-deploy]` section in `netlify.toml`, rather than relying on Netlify defaults. - -Done when: a deploy preview builds with pinned versions and returns the `noindex` header. +- Pin the MkDocs package versions in `netlify.toml`, or add a + `requirements.txt`, so preview builds match the Prow image. +- Remove the obsolete `sed` line in `netlify.toml` that rewrites + `site_url: https://kubevirt.io/docs`; `mkdocs.yml` already sets `site_url` to + `https://kubevirt.io/user-guide`. +- Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file + or a `[context.deploy-preview]` and `[context.branch-deploy]` section in + `netlify.toml`, rather than relying on Netlify defaults. + +Done when: a deploy preview builds with pinned versions and returns the +`noindex` header. diff --git a/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md index 110047f4..b99169a8 100644 --- a/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md +++ b/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md @@ -6,38 +6,67 @@ repo: https://github.com/kubevirt/user-guide/issues ## Overview -The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but nothing explains what they are for, which one is published, or when a change on `main` needs a cherry-pick. Only one version of the guide is published, so users on an older KubeVirt release read documentation for features they do not have. The release-notes regeneration step and the project's localization position are also undocumented. - -The sub-issues below record the versioning workflow, publish versioned documentation with a version selector, and close the remaining documentation-process gaps. Confirm the intended workflow with the maintainers first; the `-devel` branches exist for 1.7 and 1.8 but not 1.9, which suggests the process has drifted. +The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but +nothing explains what they are for, which one is published, or when a change on +`main` needs a cherry-pick. Only one version of the guide is published, so users +on an older KubeVirt release read documentation for features they do not have. +The release-notes regeneration step and the project's localization position are +also undocumented. + +The sub-issues below record the versioning workflow, publish versioned +documentation with a version selector, and close the remaining +documentation-process gaps. Confirm the intended workflow with the maintainers +first; the `-devel` branches exist for 1.7 and 1.8 but not 1.9, which suggests +the process has drifted. ## Sub-issues ### Document the content versioning model -In `CONTRIBUTING.md`, and summarized on the Contributing page, state what the `release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are cut relative to a KubeVirt release, which branch is published, and how a contributor decides whether a change on `main` needs a cherry-pick. Confirm the intended workflow with the maintainers before writing. +In `CONTRIBUTING.md`, and summarized on the Contributing page, state what the +`release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are +cut relative to a KubeVirt release, which branch is published, and how a +contributor decides whether a change on `main` needs a cherry-pick. Confirm the +intended workflow with the maintainers before writing. Done when: a contributor can decide from the text alone whether to cherry-pick. ### Publish versioned documentation with a version selector -Publish versioned documentation using either `mike` with the theme's `extra.version.provider: mike` setting, or a build per release branch published under a `/vX.Y/` path. Publish at least the supported N, N-1, and N-2 minors alongside `latest`. Start by prototyping the build locally and documenting the release-time steps; the Netlify and Prow changes can follow in a second pull request. +Publish versioned documentation using either `mike` with the theme's +`extra.version.provider: mike` setting, or a build per release branch published +under a `/vX.Y/` path. Publish at least the supported N, N-1, and N-2 minors +alongside `latest`. Start by prototyping the build locally and documenting the +release-time steps; the Netlify and Prow changes can follow in a second pull +request. -Done when: the published guide shows a version selector with at least three versions. +Done when: the published guide shows a version selector with at least three +versions. ### Document the release-notes update process -Record when `update_changelog.sh` is run, by whom, and how the result is reviewed, so the Release Notes page continues to be regenerated after maintainer turnover. Add this to `CONTRIBUTING.md` next to the versioning model. +Record when `update_changelog.sh` is run, by whom, and how the result is +reviewed, so the Release Notes page continues to be regenerated after maintainer +turnover. Add this to `CONTRIBUTING.md` next to the versioning model. Done when: the process is written down and names a responsible role. ### Add a localization statement -Add a short "Localization" statement to `CONTRIBUTING.md` that records the project's current position: English only, translations not currently accepted, or translations welcome via a stated process. If translations are anticipated within the next few releases, move content to `docs/en/` now and configure the `mkdocs-static-i18n` plugin so the redirects and `.nav.yml` files only need to change once. +Add a short "Localization" statement to `CONTRIBUTING.md` that records the +project's current position: English only, translations not currently accepted, +or translations welcome via a stated process. If translations are anticipated +within the next few releases, move content to `docs/en/` now and configure the +`mkdocs-static-i18n` plugin so the redirects and `.nav.yml` files only need to +change once. Done when: a prospective translator knows whether and how to contribute. ### Ask about a site-wide search across the user guide, API reference, and quickstarts -Ask the KubeVirt website maintainers whether the API reference and quickstarts can be indexed by the same search as the user guide, for example by moving the user guide search to a site-wide index. Record the decision in this issue and, if agreed, open a follow-up with the implementation plan. +Ask the KubeVirt website maintainers whether the API reference and quickstarts +can be indexed by the same search as the user guide, for example by moving the +user guide search to a site-wide index. Record the decision in this issue and, +if agreed, open a follow-up with the implementation plan. Done when: a decision is recorded. diff --git a/analyses/2026/kubevirt/issues/add-troubleshooting-page.md b/analyses/2026/kubevirt/issues/add-troubleshooting-page.md index 61f8e20a..420e3a1c 100644 --- a/analyses/2026/kubevirt/issues/add-troubleshooting-page.md +++ b/analyses/2026/kubevirt/issues/add-troubleshooting-page.md @@ -9,27 +9,44 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The guide has no page a user can turn to when something goes wrong. The Virtualization Debugging section is written for developers who need to attach `gdb` or `strace` to QEMU, and the troubleshooting notes that do exist for users are embedded in unrelated pages such as Accessing Virtual Machines and Memory Dump. +The guide has no page a user can turn to when something goes wrong. The +Virtualization Debugging section is written for developers who need to attach +`gdb` or `strace` to QEMU, and the troubleshooting notes that do exist for users +are embedded in unrelated pages such as Accessing Virtual Machines and Memory +Dump. -Add a Troubleshooting page, separate from Virtualization Debugging, that lists common symptoms with likely causes and links to the fix. Start with these symptoms: +Add a Troubleshooting page, separate from Virtualization Debugging, that lists +common symptoms with likely causes and links to the fix. Start with these +symptoms: - A VirtualMachineInstance stuck in `Scheduling` or `Pending`. - A failed live migration. - Console or VNC connection errors. - Missing `qemu-guest-agent` data. -For each symptom, give the `kubectl` or `virtctl` command that reveals the cause, the two or three most likely causes, and a link to the page that explains the fix. Move the troubleshooting notes from Accessing Virtual Machines and Memory Dump onto this page, or link to them from it. Add the page to `docs/.nav.yml` near Virtualization Debugging and link to it from the Getting Started page. +For each symptom, give the `kubectl` or `virtctl` command that reveals the +cause, the two or three most likely causes, and a link to the page that explains +the fix. Move the troubleshooting notes from Accessing Virtual Machines and +Memory Dump onto this page, or link to them from it. Add the page to +`docs/.nav.yml` near Virtualization Debugging and link to it from the Getting +Started page. ## What you expected -A user who hits a common failure can find a symptom-oriented page in the guide that leads them to the cause and the fix without reading the developer debugging section. +A user who hits a common failure can find a symptom-oriented page in the guide +that leads them to the cause and the fix without reading the developer debugging +section. ## URL -- https://kubevirt.io/user-guide/debug_virt_stack/debug/ (`docs/debug_virt_stack/debug.md`) -- https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ (`docs/user_workloads/accessing_virtual_machines.md`) -- https://kubevirt.io/user-guide/compute/memory_dump/ (`docs/compute/memory_dump.md`) +- https://kubevirt.io/user-guide/debug_virt_stack/debug/ + (`docs/debug_virt_stack/debug.md`) +- https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ + (`docs/user_workloads/accessing_virtual_machines.md`) +- https://kubevirt.io/user-guide/compute/memory_dump/ + (`docs/compute/memory_dump.md`) ## Additional context -Keep the first version small. Four symptoms with accurate causes are more useful than a long list; the page can grow as users report more. +Keep the first version small. Four symptoms with accurate causes are more useful +than a long list; the page can grow as users report more. diff --git a/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md b/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md index b7b1545b..c15906c2 100644 --- a/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md +++ b/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md @@ -9,18 +9,31 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The CNCF website guidelines require every project property to show the Linux Foundation copyright line, the project's CNCF maturity statement, the CNCF logo, and a link to the LF Projects policies. The user guide footer shows none of these, and the repository has no root `CODE_OF_CONDUCT.md`. +The CNCF website guidelines require every project property to show the Linux +Foundation copyright line, the project's CNCF maturity statement, the CNCF logo, +and a link to the LF Projects policies. The user guide footer shows none of +these, and the repository has no root `CODE_OF_CONDUCT.md`. Make these changes: -1. In `mkdocs.yml`, set `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"`. -2. Add `overrides/partials/copyright.html` (or a `footer.html` override) that appends "We are a Cloud Native Computing Foundation incubating project", the CNCF logo linked to `https://cncf.io`, and a link to `https://lfprojects.org/policies/` for trademark and terms. Match the wording and links used in the main website footer so the two properties read as one. -3. Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of conduct, so the file is present where the CNCF checklist expects it rather than only inherited from the organization default. -4. Add a note to the README naming the file to edit when the project's CNCF maturity status changes, so the footer statement does not go stale. +1. In `mkdocs.yml`, set + `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"`. +2. Add `overrides/partials/copyright.html` (or a `footer.html` override) that + appends "We are a Cloud Native Computing Foundation incubating project", the + CNCF logo linked to `https://cncf.io`, and a link to + `https://lfprojects.org/policies/` for trademark and terms. Match the wording + and links used in the main website footer so the two properties read as one. +3. Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code + of conduct, so the file is present where the CNCF checklist expects it rather + than only inherited from the organization default. +4. Add a note to the README naming the file to edit when the project's CNCF + maturity status changes, so the footer statement does not go stale. ## What you expected -The user guide footer shows the same copyright, maturity statement, CNCF logo, and policy link as `kubevirt.io`, and the repository root contains a code of conduct. +The user guide footer shows the same copyright, maturity statement, CNCF logo, +and policy link as `kubevirt.io`, and the repository root contains a code of +conduct. ## URL @@ -29,4 +42,5 @@ The user guide footer shows the same copyright, maturity statement, CNCF logo, a ## Additional context -The theme's `custom_dir` must be set to `overrides` in `mkdocs.yml` for partial overrides to take effect; check whether it already is. +The theme's `custom_dir` must be set to `overrides` in `mkdocs.yml` for partial +overrides to take effect; check whether it already is. From 9a39c9150a1a66eb514528b2120e0d25f3b82fb7 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 12 Oct 2026 20:09:14 -0700 Subject: [PATCH 04/31] removed issues-coverage due to line length Signed-off-by: Bruce Hamilton --- .cspell.yml | 1 + analyses/2026/kubevirt/issues-coverage.md | 171 ---------------------- 2 files changed, 1 insertion(+), 171 deletions(-) delete mode 100644 analyses/2026/kubevirt/issues-coverage.md diff --git a/.cspell.yml b/.cspell.yml index 9da23446..052d623f 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -100,3 +100,4 @@ words: - yaspeller - kubevirt - viewports + - rniw diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md deleted file mode 100644 index 84fe06b6..00000000 --- a/analyses/2026/kubevirt/issues-coverage.md +++ /dev/null @@ -1,171 +0,0 @@ -# Issue coverage report - -This report maps every recommendation in `.github/input/ai-ranked-recommendations.csv` to the issue file in `.github/output/issues/` that covers it. It is kept outside the issues directory so it is not uploaded as an issue. - -## Issue files - -| File | Label | Sub-issues | -|---|---|---| -| `U-create-getting-started-path.md` | urgent | 6 | -| `U-fix-navigation-gaps.md` | urgent | 7 | -| `U-mkdocs-improvements.md` | urgent | 4 | -| `U-document-v19-features.md` | high | 6 | -| `add-troubleshooting-page.md` | high | standalone | -| `U-accessibility-improvements.md` | high | 9 | -| `U-inclusive-language-updates.md` | high | 6 | -| `U-build-contributor-guide.md` | urgent | 9 | -| `U-publish-versioned-docs.md` | high | 5 | -| `U-document-community-channels.md` | urgent | 5 | -| `fix-footer-cncf-compliance.md` | urgent | standalone | -| `U-fix-kubevirt-io-gaps.md` | urgent | 10 | -| `U-enable-analytics.md` | high | 3 | -| `U-document-site-ownership.md` | high | 7 | - -## Recommendation mapping - - - -## Priority adjustments - -Umbrella labels follow the highest-priority sub-issue, with these exceptions: - - - -## Notes for the writer - -- `U-fix-kubevirt-io-gaps.md` describes changes to `kubevirt/kubevirt.github.io`. Its `repo` is set to the user guide per the instructions; change it to `https://github.com/kubevirt/kubevirt.github.io/issues` if the upload should target the website repository directly. -- Recommendations 75, 77, 100, and 101 each have a user-guide half and a website half and appear in two files. - - -## Counts - -- Recommendations: 114 -- Covered by an issue: 109 -- Not an issue: 5 -- Issue files: 14 (12 umbrella, 2 standalone) -- Sub-issues: 77 From 65523add34ed8f222eba4ae43c81f1995bd5c06d Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Mon, 12 Oct 2026 20:37:21 -0700 Subject: [PATCH 05/31] line length fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/U-build-contributor-guide.md | 2 +- .../2026/kubevirt/issues/U-create-getting-started-path.md | 4 ++-- analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md index 18ab1ac2..7fe2be68 100644 --- a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md +++ b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md @@ -107,7 +107,7 @@ linked. Done when: new pull requests open with the checklist. -### State the code-freeze requirement and a stale-PR policy, and triage open pull requests +### Code-freeze requirement, stale-PR policy, triage open pull requests - On the Contributing page, state that the VEP checklist requires the docs PR to be merged by code freeze. diff --git a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md index b6dc5616..46aa24d3 100644 --- a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md +++ b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md @@ -52,7 +52,7 @@ will have at the end. Add a closing link to the Getting Started page. Done when: both pages link to Getting Started and the Quickstarts page states its prerequisites. -### Rewrite Basic Use as "Your first VirtualMachine" and fix the Lifecycle manifest reference +### Rewrite Basic Use as and fix the Lifecycle manifest reference Rewrite `docs/user_workloads/basic_use.md` into a short page that presents VirtualMachine as the primary object and VirtualMachineInstance as the running @@ -94,7 +94,7 @@ Accessing Virtual Machines. Done when: the Installation page no longer ends on an advanced topic. -### Expand the virtctl page to cover all client binaries and rename it "Installing virtctl" +### Expand the virtctl page and rename it "Installing virtctl" Expand `docs/user_workloads/virtctl_client_tool.md` to cover every published client binary. Use the Material theme's content tabs for Linux, macOS, and diff --git a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md index 48703c75..20848d7c 100644 --- a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md +++ b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md @@ -21,7 +21,7 @@ order; when a file name changes, add a redirect in `mkdocs.yml`. ## Sub-issues -### Add the Plugins page to the navigation and delete the duplicate Windows virtio drivers page +### Add the Plugins page and delete duplicate Windows virtio drivers page Add `plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is discoverable from somewhere other than the deprecated Hook Sidecar page. From 9909ed55620d2a8039158ac75373e89dc9b247e6 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 02:02:26 -0700 Subject: [PATCH 06/31] umbrella issues rework Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 254 ++++++++++++++++++ .../issues/9001-add-getting-started-page.md | 36 +++ .../kubevirt/issues/9002-rewrite-basic-use.md | 34 +++ .../issues/9003-fix-welcome-page-links.md | 29 ++ .../9004-restructure-installation-page.md | 31 +++ .../9005-create-installing-virtctl-page.md | 33 +++ .../issues/9006-enable-code-copy-search.md | 33 +++ .../issues/9007-convert-shell-code-blocks.md | 40 +++ .../issues/9008-fix-navigation-orphans.md | 36 +++ .../issues/9009-add-section-landing-pages.md | 35 +++ .../issues/9010-rename-api-page-titles.md | 41 +++ ...9011-remove-legacy-installation-content.md | 32 +++ .../9012-document-virtualmachinebackup-api.md | 35 +++ .../issues/9013-document-v19-features.md | 33 +++ .../issues/9014-create-virtctl-reference.md | 32 +++ .../issues/9015-add-feature-gate-table.md | 33 +++ .../issues/9016-add-troubleshooting-page.md | 35 +++ ...17-standardize-feature-state-admonition.md | 36 +++ .../issues/9018-document-versioning-model.md | 31 +++ .../issues/9019-publish-versioned-docs.md | 37 +++ .../issues/9020-expand-contributing-guide.md | 34 +++ .../kubevirt/issues/9021-add-style-guide.md | 36 +++ .../issues/9022-add-pull-request-template.md | 35 +++ .../kubevirt/issues/9023-add-owners-files.md | 34 +++ .../issues/9024-give-docs-sig-home.md | 37 +++ .../kubevirt/issues/9025-triage-open-prs.md | 33 +++ .../issues/9026-add-maintainers-file.md | 33 +++ .../issues/9027-reword-minimizing-language.md | 40 +++ .../kubevirt/issues/9028-add-ci-doc-checks.md | 32 +++ .../9029-fix-legacy-master-references.md | 38 +++ .../issues/9030-add-community-page.md | 35 +++ .../9031-add-community-adoption-links.md | 34 +++ .../issues/9032-add-footer-social-links.md | 31 +++ .../issues/9033-fix-logo-and-unused-assets.md | 30 +++ .../issues/9034-add-contributing-overview.md | 30 +++ .../issues/9035-add-help-and-vep-guidance.md | 32 +++ .../kubevirt/issues/9036-link-issue-lists.md | 32 +++ .../9037-add-first-change-walkthrough.md | 31 +++ .../9038-standardize-good-first-issue.md | 34 +++ .../issues/9039-triage-issue-backlog.md | 32 +++ .../issues/9040-add-governance-section.md | 32 +++ .../issues/9041-document-content-boundary.md | 40 +++ .../issues/9042-add-api-reference-link.md | 31 +++ .../issues/9043-audit-kubevirt-docs.md | 34 +++ .../kubevirt/issues/9044-audit-cdi-docs.md | 31 +++ .../issues/9045-decide-converge-toolchains.md | 33 +++ .../kubevirt/issues/9046-fix-guide-footer.md | 34 +++ .../issues/9047-fix-website-footer.md | 32 +++ .../issues/9048-fix-contrast-and-colors.md | 31 +++ .../kubevirt/issues/9049-fix-mobile-tables.md | 39 +++ .../issues/9050-split-disks-networks-pages.md | 36 +++ .../9051-split-migration-release-notes.md | 39 +++ .../issues/9052-publish-brand-reference.md | 33 +++ .../kubevirt/issues/9053-add-adopters-page.md | 32 +++ .../issues/9054-show-adopter-use-cases.md | 34 +++ .../issues/9055-add-blog-categories.md | 31 +++ .../issues/9056-enable-guide-analytics.md | 32 +++ .../9057-fix-robots-and-site-analytics.md | 32 +++ .../issues/9058-fix-guide-preview-builds.md | 33 +++ .../2026/kubevirt/issues/9059-unify-search.md | 32 +++ .../9060-document-site-infrastructure.md | 35 +++ .../U-9061-create-getting-started-path.md | 21 ++ .../issues/U-9062-fix-navigation-gaps.md | 21 ++ .../U-9063-fill-feature-coverage-gaps.md | 19 ++ .../issues/U-9064-publish-versioned-docs.md | 17 ++ .../issues/U-9065-build-contributor-guide.md | 20 ++ .../U-9066-improve-contributing-page.md | 20 ++ .../U-9067-document-community-channels.md | 19 ++ .../U-9068-inclusive-language-updates.md | 17 ++ .../U-9069-accessibility-improvements.md | 18 ++ .../issues/U-9070-fix-website-compliance.md | 19 ++ .../issues/U-9071-enable-analytics-seo.md | 18 ++ .../issues/U-9072-document-site-ownership.md | 19 ++ .../issues/U-accessibility-improvements.md | 123 --------- .../issues/U-build-contributor-guide.md | 135 ---------- .../issues/U-create-getting-started-path.md | 111 -------- .../issues/U-document-community-channels.md | 85 ------ .../issues/U-document-site-ownership.md | 95 ------- .../issues/U-document-v19-features.md | 78 ------ .../kubevirt/issues/U-enable-analytics.md | 44 --- .../kubevirt/issues/U-fix-kubevirt-io-gaps.md | 121 --------- .../kubevirt/issues/U-fix-navigation-gaps.md | 95 ------- .../issues/U-inclusive-language-updates.md | 76 ------ .../kubevirt/issues/U-mkdocs-improvements.md | 63 ----- .../issues/U-publish-versioned-docs.md | 72 ----- .../issues/add-troubleshooting-page.md | 52 ---- .../issues/fix-footer-cncf-compliance.md | 46 ---- 87 files changed, 2513 insertions(+), 1196 deletions(-) create mode 100644 analyses/2026/kubevirt/issues-coverage.md create mode 100644 analyses/2026/kubevirt/issues/9001-add-getting-started-page.md create mode 100644 analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md create mode 100644 analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md create mode 100644 analyses/2026/kubevirt/issues/9004-restructure-installation-page.md create mode 100644 analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md create mode 100644 analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md create mode 100644 analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md create mode 100644 analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md create mode 100644 analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md create mode 100644 analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md create mode 100644 analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md create mode 100644 analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md create mode 100644 analyses/2026/kubevirt/issues/9013-document-v19-features.md create mode 100644 analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md create mode 100644 analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md create mode 100644 analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md create mode 100644 analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md create mode 100644 analyses/2026/kubevirt/issues/9018-document-versioning-model.md create mode 100644 analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md create mode 100644 analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md create mode 100644 analyses/2026/kubevirt/issues/9021-add-style-guide.md create mode 100644 analyses/2026/kubevirt/issues/9022-add-pull-request-template.md create mode 100644 analyses/2026/kubevirt/issues/9023-add-owners-files.md create mode 100644 analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md create mode 100644 analyses/2026/kubevirt/issues/9025-triage-open-prs.md create mode 100644 analyses/2026/kubevirt/issues/9026-add-maintainers-file.md create mode 100644 analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md create mode 100644 analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md create mode 100644 analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md create mode 100644 analyses/2026/kubevirt/issues/9030-add-community-page.md create mode 100644 analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md create mode 100644 analyses/2026/kubevirt/issues/9032-add-footer-social-links.md create mode 100644 analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md create mode 100644 analyses/2026/kubevirt/issues/9034-add-contributing-overview.md create mode 100644 analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md create mode 100644 analyses/2026/kubevirt/issues/9036-link-issue-lists.md create mode 100644 analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md create mode 100644 analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md create mode 100644 analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md create mode 100644 analyses/2026/kubevirt/issues/9040-add-governance-section.md create mode 100644 analyses/2026/kubevirt/issues/9041-document-content-boundary.md create mode 100644 analyses/2026/kubevirt/issues/9042-add-api-reference-link.md create mode 100644 analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md create mode 100644 analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md create mode 100644 analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md create mode 100644 analyses/2026/kubevirt/issues/9046-fix-guide-footer.md create mode 100644 analyses/2026/kubevirt/issues/9047-fix-website-footer.md create mode 100644 analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md create mode 100644 analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md create mode 100644 analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md create mode 100644 analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md create mode 100644 analyses/2026/kubevirt/issues/9052-publish-brand-reference.md create mode 100644 analyses/2026/kubevirt/issues/9053-add-adopters-page.md create mode 100644 analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md create mode 100644 analyses/2026/kubevirt/issues/9055-add-blog-categories.md create mode 100644 analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md create mode 100644 analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md create mode 100644 analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md create mode 100644 analyses/2026/kubevirt/issues/9059-unify-search.md create mode 100644 analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md create mode 100644 analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md create mode 100644 analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md create mode 100644 analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md create mode 100644 analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md create mode 100644 analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md create mode 100644 analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md create mode 100644 analyses/2026/kubevirt/issues/U-9067-document-community-channels.md create mode 100644 analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md create mode 100644 analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md create mode 100644 analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md create mode 100644 analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md create mode 100644 analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md delete mode 100644 analyses/2026/kubevirt/issues/U-accessibility-improvements.md delete mode 100644 analyses/2026/kubevirt/issues/U-build-contributor-guide.md delete mode 100644 analyses/2026/kubevirt/issues/U-create-getting-started-path.md delete mode 100644 analyses/2026/kubevirt/issues/U-document-community-channels.md delete mode 100644 analyses/2026/kubevirt/issues/U-document-site-ownership.md delete mode 100644 analyses/2026/kubevirt/issues/U-document-v19-features.md delete mode 100644 analyses/2026/kubevirt/issues/U-enable-analytics.md delete mode 100644 analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md delete mode 100644 analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md delete mode 100644 analyses/2026/kubevirt/issues/U-inclusive-language-updates.md delete mode 100644 analyses/2026/kubevirt/issues/U-mkdocs-improvements.md delete mode 100644 analyses/2026/kubevirt/issues/U-publish-versioned-docs.md delete mode 100644 analyses/2026/kubevirt/issues/add-troubleshooting-page.md delete mode 100644 analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md new file mode 100644 index 00000000..3e3386d2 --- /dev/null +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -0,0 +1,254 @@ +# 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. + +## Issues + +| Issue | Title | Label | File | +|---|---|---|---| +| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | +| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | +| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | +| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | +| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | +| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | +| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | +| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | +| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | +| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | +| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | +| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | +| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | +| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | +| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | +| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | +| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | +| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | +| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | +| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | +| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | +| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | +| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | +| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | +| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | +| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | +| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | +| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | +| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | +| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | +| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | +| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | +| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | +| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | +| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | +| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | +| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | +| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | +| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | +| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | +| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | +| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | +| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | +| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | +| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | +| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | +| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | +| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | +| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | +| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | +| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | +| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | +| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | +| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | +| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | +| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | +| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | +| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | +| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | +| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | +| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | +| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | +| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | +| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | +| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | +| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | +| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | +| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | +| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | +| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | +| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | + +## Umbrella issues + +| Umbrella | Label | Sub-issues | +|---|---|---| +| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | +| #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | +| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | +| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | +| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | +| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | +| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | +| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | +| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | +| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | +| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | +| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | + +Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. + +## Recommendation mapping + +| # | Section | Area | CSV priority | Issue(s) | +|---|---|---|---|---| +| 1 | Project Documentation | Information architecture | 2 - High | #9001 | +| 2 | Project Documentation | Information architecture | 2 - High | #9002 | +| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | +| 5 | Project Documentation | Information architecture | 2 - High | #9014 | +| 6 | Project Documentation | Information architecture | 2 - High | #9015 | +| 7 | Project Documentation | Information architecture | 2 - High | #9016 | +| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | +| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 11 | Project Documentation | Information architecture | 2 - High | #9011 | +| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 14 | Project Documentation | New user content | 2 - High | #9001 | +| 15 | Project Documentation | New user content | 2 - High | #9004 | +| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | +| 17 | Project Documentation | New user content | 2 - High | #9004 | +| 18 | Project Documentation | New user content | 2 - High | #9005 | +| 19 | Project Documentation | New user content | 2 - High | #9002 | +| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | +| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | +| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | +| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | +| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | +| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | +| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | +| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | +| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | +| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | +| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | +| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | +| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | +| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | +| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | +| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | + +## Priority adjustments + +No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: + +| Issue | Label | Recommendations raised (original ranking) | Reason | +|---|---|---|---| +| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | +| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | +| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | +| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | +| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | +| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | +| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | +| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | +| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | +| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | +| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | +| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | +| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | +| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | +| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | +| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | +| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | +| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | +| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | + +## 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 diff --git a/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md b/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md new file mode 100644 index 00000000..94f0e487 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md @@ -0,0 +1,36 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md b/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md new file mode 100644 index 00000000..1c7f6288 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md @@ -0,0 +1,34 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md b/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md new file mode 100644 index 00000000..91e85c8b --- /dev/null +++ b/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md @@ -0,0 +1,29 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md b/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md new file mode 100644 index 00000000..cc5cb758 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md @@ -0,0 +1,31 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md b/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md new file mode 100644 index 00000000..eb908012 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md @@ -0,0 +1,33 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md b/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md new file mode 100644 index 00000000..d211bda8 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md @@ -0,0 +1,33 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md b/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md new file mode 100644 index 00000000..7be64563 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md @@ -0,0 +1,40 @@ +--- +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). diff --git a/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md b/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md new file mode 100644 index 00000000..6fc7a725 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md @@ -0,0 +1,36 @@ +--- +title: Fix orphaned pages and Release Notes placement in navigation #9008 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Three navigation problems make content hard to find or confusing: + +- `docs/cluster_admin/plugins.md` is not listed in `docs/cluster_admin/.nav.yml`, so the Plugins page is reachable only from the deprecated Hook Sidecar page. +- `docs/compute/windows_virtio_drivers.md` is an unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Verify the files are identical (for example with `diff`). +- Release Notes sits in the middle of the top-level list in `docs/.nav.yml`, between Storage and Contributing, which breaks the progression from concepts through administration, workloads, and infrastructure. + +Make these changes: + +1. Add `plugins.md` to `docs/cluster_admin/.nav.yml`. +2. Delete `docs/compute/windows_virtio_drivers.md` and add a redirect in `mkdocs.yml` to the User Workloads page if the old URL was ever published. +3. Move Release Notes to the end of the list in `docs/.nav.yml`, or expose it as a top-bar link. + +## What you expected + +Every page in `docs/` is reachable from the navigation, no duplicate page exists, and the top-level sections read in a logical order with Release Notes at the end. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/plugins/ +- https://kubevirt.io/user-guide/user_workloads/windows_virtio_drivers/ +- https://kubevirt.io/user-guide/release_notes/ +- `docs/.nav.yml`, `docs/cluster_admin/.nav.yml`, `docs/compute/windows_virtio_drivers.md`, `mkdocs.yml` + +## Additional context + +This work is a quick win. Check the deployed site to see whether `/compute/windows_virtio_drivers/` was ever served before you decide on the redirect. + +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). diff --git a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md new file mode 100644 index 00000000..77ff4bee --- /dev/null +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -0,0 +1,35 @@ +--- +title: Add landing pages to Compute, Network, and Storage #9009 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Compute, Network, and Storage sections each hold 10 to 20 pages with no introduction. Readers see a flat list and cannot tell which page matches their task. + +Add a short landing page to each section, `docs/compute/index.md`, `docs/network/index.md`, and `docs/storage/index.md`, and list it first in the section's navigation. Each page explains in two or three sentences what the section covers, then groups its pages by task with a one-line description per link. For example, the Storage page uses these groups: + +- Provisioning disks +- Importing images +- Snapshots and backup +- Moving data between clusters + +Propose equivalent task groups for Compute (for example CPU and memory, live migration, devices) and Network (for example interfaces, services, binding plugins). Ask a maintainer to confirm the groupings. + +## What you expected + +Selecting a section shows a page that explains its scope and points to the right page for each common task. + +## URL + +- https://kubevirt.io/user-guide/compute/ +- https://kubevirt.io/user-guide/network/ +- https://kubevirt.io/user-guide/storage/ +- New files `docs/compute/index.md`, `docs/network/index.md`, `docs/storage/index.md`; the existing `.nav.yml` files in each directory + +## Additional context + +Page renames in #9010 change some link titles, so write the landing pages with the final titles or update them afterward. + +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). diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md new file mode 100644 index 00000000..263a8296 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -0,0 +1,41 @@ +--- +title: Rename API-centric titles and group legacy workload pages #9010 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Several page titles name an API instead of the task the reader wants to do, and the User Workloads "Workloads" group mixes current and legacy mechanisms. + +Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: + +| Current title | Proposed title | +| --- | --- | +| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | +| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | +| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | +| Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | + +Choose the last title after reading the page; ask the maintainers if the purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update inbound links. + +Then reorder the "Workloads" group in `docs/user_workloads/.nav.yml`. List current mechanisms (instance types, VirtualMachine Templates, pools) first. Place legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) under a clearly labeled "Legacy" heading, or at the end of the group. + +## What you expected + +Titles tell readers what they can accomplish, and the Workloads group leads with current mechanisms while legacy pages are labeled as such. + +## URL + +- https://kubevirt.io/user-guide/storage/clone_api/ +- https://kubevirt.io/user-guide/storage/export_api/ +- https://kubevirt.io/user-guide/storage/snapshot_restore_api/ +- https://kubevirt.io/user-guide/storage/migration_controller/ +- https://kubevirt.io/user-guide/user_workloads/instancetypes/ +- `docs/storage/.nav.yml`, `docs/user_workloads/.nav.yml`, `mkdocs.yml` + +## Additional context + +Prefer keeping file names unchanged to avoid broken inbound links, unless the rename adds clear value. + +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). diff --git a/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md b/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md new file mode 100644 index 00000000..e9d5292d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md @@ -0,0 +1,32 @@ +--- +title: Remove or archive legacy installation content #9011 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Installation page keeps instructions for platforms and tools that may no longer be supported, and its OKD instructions link to OpenShift 4.10 documentation, which is out of date. Readers cannot tell whether these paths still work. + +Review these sections of `docs/cluster_admin/installation.md` with the maintainers: + +- "From Service Catalog as an APB" under "Installing KubeVirt on OKD": Is the OKD Service Catalog APB path still supported? +- "Installing KubeVirt on k3OS": Is k3OS still a supported platform? +- The OpenShift 4.10 links, including the SCC link: Which current version should the page link to, or is a version-independent URL available? + +Then act on the answers. Delete unsupported sections, or move them to an "Archived" page with a clear notice that they are not maintained. Update the OpenShift links to the current version or a version-independent URL. Verify that every remaining link in the page resolves. + +## What you expected + +The Installation page describes only paths that KubeVirt supports today, and every external link points to current documentation. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/installation/ +- `docs/cluster_admin/installation.md` + +## Additional context + +The maintainers must answer the support questions before you delete content. This work overlaps with the restructure in #9004, which moves the same sections; agree on the order of the two pull requests to avoid conflicts. + +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). diff --git a/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md b/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md new file mode 100644 index 00000000..0f75375a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md @@ -0,0 +1,35 @@ +--- +title: Document the VirtualMachineBackup API #9012 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The `VirtualMachineBackup` API, introduced in v1.9, appears only in `docs/release_notes.md`. Users who read the Storage section find snapshots and export but no mention of backup, so they cannot discover or use the feature. + +Add a section to an existing Storage page, or a new `docs/storage/` page added to `docs/storage/.nav.yml`, that covers: + +- What a VirtualMachineBackup does and how it differs from a VirtualMachineSnapshot and a VMExport. +- A minimal VirtualMachineBackup manifest and the `kubectl` commands to create it and watch its progress. +- The conditions a backup reports (`Progressing`, `Complete`, and `Failed`) and what each means. +- Prerequisites, such as feature gates and storage requirements. Ask the maintainers which gates and requirements apply. +- Links to the Snapshot Restore API and Export API pages. + +Take the facts from the release notes entries for VirtualMachineBackup and confirm technical details with the feature author. Phrase anything you cannot confirm as a question to the maintainers. + +## What you expected + +A user can find the Backup API from the Storage section and run a first backup by following the page. + +## URL + +- https://kubevirt.io/user-guide/storage/snapshot_restore_api/ +- https://kubevirt.io/user-guide/release_notes/ +- `docs/storage/.nav.yml` and a new or edited file in `docs/storage/` + +## Additional context + +Related v1.9 documentation gaps are in #9013. If a Storage landing page exists (#9009), link the new content from it. + +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). diff --git a/analyses/2026/kubevirt/issues/9013-document-v19-features.md b/analyses/2026/kubevirt/issues/9013-document-v19-features.md new file mode 100644 index 00000000..5dbfa3f1 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9013-document-v19-features.md @@ -0,0 +1,33 @@ +--- +title: Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression #9013 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Three v1.9 features appear only in `docs/release_notes.md`, so users cannot find them in the feature pages. Add a section for each: + +- **`CrossArchitectureVirtualization` feature gate** (Alpha): Add a section to a Compute page or to `docs/cluster_admin/activating_feature_gates.md`. Explain that VMs can run on nodes with a different architecture through QEMU software emulation (TCG), that the scheduler prefers native-architecture nodes and falls back to emulation, and how to enable the gate. +- **Masquerade `PortRanges`** (Alpha, guarded by the `PortRangesSpec` feature gate): Add a section to `docs/network/interfaces_and_networks.md` that shows how to define port ranges on a masquerade interface, with an example and the gate to enable. +- **MigrationPolicy compression**: Add a section to `docs/cluster_admin/migration_policies.md` that explains the `.spec.experimental.compression` field. It compresses the live migration data stream, and only the `zstd` algorithm is supported. Include an example MigrationPolicy. + +Use the release notes entries as the starting point. Ask the feature authors to confirm limitations, and phrase unconfirmed details as questions. + +## What you expected + +Each feature is documented next to related content with an example manifest, the required feature gate, and its maturity stage. + +## URL + +- https://kubevirt.io/user-guide/release_notes/ +- https://kubevirt.io/user-guide/network/interfaces_and_networks/ +- https://kubevirt.io/user-guide/cluster_admin/migration_policies/ +- https://kubevirt.io/user-guide/cluster_admin/activating_feature_gates/ +- `docs/network/interfaces_and_networks.md`, `docs/cluster_admin/migration_policies.md`, `docs/cluster_admin/activating_feature_gates.md` + +## Additional context + +The feature-gate table in #9015 should list these gates. The Backup API is covered separately in #9012. + +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). diff --git a/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md b/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md new file mode 100644 index 00000000..90edf227 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md @@ -0,0 +1,32 @@ +--- +title: Create a virtctl command reference #9014 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The `virtctl` page covers only downloading and installing the client. No page lists the subcommands, so users must read many feature pages, or run `virtctl --help`, to learn what the tool does. + +Create a `docs/user_workloads/virtctl_reference.md` page, or expand the existing `virtctl` page beyond installation, and add it to `docs/user_workloads/.nav.yml`. The page lists each `virtctl` subcommand in a table with: + +- The command name, in code formatting. +- A one-line description. +- A link to the feature page that explains it in context, for example `virtctl console` to Accessing Virtual Machines and `virtctl vmexport` to the Export API page. + +Group the commands by task, such as VM lifecycle, access, storage, and diagnostics. Generate the command list from `virtctl --help` of a current release, and ask the maintainers whether the list can be produced automatically from the `kubevirt/kubevirt` source to avoid drift. + +## What you expected + +A reader finds every `virtctl` subcommand in one table and can follow a link to learn how to use it. + +## 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 + +If #9005 renames the `virtctl` page to "Installing virtctl", keep installation and reference content on separate pages and link them to each other. + +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). diff --git a/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md b/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md new file mode 100644 index 00000000..dad128c0 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md @@ -0,0 +1,33 @@ +--- +title: Add a feature-gate table #9015 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Activating and Deactivating Feature Gates page explains the Alpha, Beta, and GA stages but does not list the gates themselves. Readers must search the guide and the release notes to learn which gates exist, their maturity, and where they are documented. + +Add a table to `docs/cluster_admin/activating_feature_gates.md` with one row per feature gate and these columns: + +- Gate name, in code formatting. +- Stage: Alpha, Beta, GA, or Deprecated. +- Version in which the gate was introduced or graduated. +- Link to the page that documents the feature. + +Source the rows from the `kubevirt/kubevirt` feature gate definitions and the release notes. Ask the maintainers whether this table can be generated from the `kubevirt/kubevirt` source to avoid drift, and if so, describe the generation step in the page's source comments or in `CONTRIBUTING.md`. If gates have no documentation, leave the link empty and note it in the pull request. + +## What you expected + +A reader finds every feature gate, its stage, and its documentation in one table, and the table has a defined way to stay current. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/activating_feature_gates/ +- `docs/cluster_admin/activating_feature_gates.md` + +## Additional context + +Include the gates documented in #9013 (`CrossArchitectureVirtualization` and `PortRangesSpec`). The Arm64 page `docs/cluster_admin/feature_gate_status_on_Arm64.md` is a separate topic; link to it rather than merging it. + +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). diff --git a/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md b/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md new file mode 100644 index 00000000..e2b29270 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md @@ -0,0 +1,35 @@ +--- +title: Add a user-facing Troubleshooting page #9016 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Troubleshooting content is scattered. The Virtualization Debugging section targets developers (`strace`, `gdb`, `virsh`), while user-level notes sit inside Accessing Virtual Machines and Memory Dump. A user whose VirtualMachineInstance does not start has no obvious place to look. + +Add `docs/user_workloads/troubleshooting.md` and list it in `docs/user_workloads/.nav.yml`. Structure the page by symptom. For each symptom, list likely causes and link to the fix: + +- A VirtualMachineInstance stuck in `Scheduling` or `Pending`. +- A failed live migration. +- Console or VNC connection errors. +- Missing `qemu-guest-agent` data. + +Consolidate the troubleshooting notes now embedded in `docs/user_workloads/accessing_virtual_machines.md` and `docs/compute/memory_dump.md` into the new page, or link to them from it. Link the new page from the Virtualization Debugging introduction as the first stop before the developer-level guides. Confirm causes and fixes with maintainers, and phrase uncertain items as questions. + +## What you expected + +A user who sees a failure finds the symptom on one page, learns the likely causes, and follows a link to the fix. + +## URL + +- https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ +- https://kubevirt.io/user-guide/compute/memory_dump/ +- https://kubevirt.io/user-guide/debug_virt_stack/debug/ +- `docs/user_workloads/accessing_virtual_machines.md`, `docs/compute/memory_dump.md`, `docs/debug_virt_stack/debug.md` + +## Additional context + +Start with the four symptoms above and leave room to grow. Ask maintainers for the most frequent support questions from the Slack channel and issue tracker to prioritize further entries. + +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). diff --git a/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md b/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md new file mode 100644 index 00000000..8c743d41 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md @@ -0,0 +1,36 @@ +--- +title: Standardize the feature-state admonition #9017 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Feature pages mark their maturity with a `**FEATURE STATE:**` line, but the format varies. Some pages state a version only (`KubeVirt v0.43`), some add a stage (`v1.9.0: Beta`, `(Alpha)`, `(experimental support)`), and some leave the value empty or use a heading (`### **FEATURE STATE:**`). The guide publishes only one version, so readers rely on these markers to know whether a feature exists in their release and how mature it is. + +Define one admonition format that states the version introduced and the current stage (Alpha, Beta, GA, or Deprecated), and apply it to every page that has a feature-state marker: + +- `docs/compute/live_migration.md`, `numa.md`, `persistent_tpm_and_uefi_state.md`, and `dra_gpu.md` +- `docs/cluster_admin/confidential_computing.md` +- `docs/user_workloads/vm_templates.md`, `deploy_common_instancetypes.md`, `presets.md`, and `instancetypes.md` + +Use the existing `admonition` extension, for example `!!! info "Feature state"` followed by a line such as `Introduced in KubeVirt v1.9 (Alpha)`. Fill in the empty markers using the release notes. Ask the maintainers for the current stage of any feature you cannot confirm. Add the chosen format, with an example, to `CONTRIBUTING.md` so new pages follow it. + +## What you expected + +Every feature page shows the same admonition with the introduced version and stage, and contributors know how to write it for new pages. + +## URL + +- https://kubevirt.io/user-guide/compute/live_migration/ +- https://kubevirt.io/user-guide/compute/numa/ +- https://kubevirt.io/user-guide/compute/dra_gpu/ +- https://kubevirt.io/user-guide/cluster_admin/confidential_computing/ +- https://kubevirt.io/user-guide/user_workloads/instancetypes/ +- The `docs/` files listed above and `CONTRIBUTING.md` + +## Additional context + +The feature-gate table in #9015 reports the same stages; keep the two consistent. Contributor guide additions are tracked in #9020. + +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). diff --git a/analyses/2026/kubevirt/issues/9018-document-versioning-model.md b/analyses/2026/kubevirt/issues/9018-document-versioning-model.md new file mode 100644 index 00000000..3fe4ba7a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9018-document-versioning-model.md @@ -0,0 +1,31 @@ +--- +title: Document the content versioning model, release-notes process, and localization #9018 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but no page explains how they work. Contributors cannot tell which branch is published or whether a change on `main` needs a cherry-pick. The release notes are regenerated with `update_changelog.sh`, but nothing records who runs it or when. The project also has no stated position on translations. + +Add three sections to `CONTRIBUTING.md`, and summarize the first on the Contributing page (`docs/contributing.md`): + +1. **Content versioning.** State what the `release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are cut relative to a KubeVirt release, which branch is published, and how a contributor decides whether a change needs a cherry-pick. The `-devel` branches exist for 1.7 and 1.8 but not 1.9; ask the maintainers to confirm the intended workflow before you write it. +2. **Release notes.** Describe when `update_changelog.sh` runs, who runs it, and how the result is reviewed. +3. **Localization.** Record the current position: English only, translations not accepted, or translations welcome through a stated process. Ask the maintainers which applies. If they expect translations within a few releases, open a follow-up issue to move content to `docs/en/` and configure the `mkdocs-static-i18n` plugin. + +## What you expected + +A contributor reads `CONTRIBUTING.md` and knows which branch to target, whether to cherry-pick, how release notes are produced, and whether translations are accepted. + +## URL + +- https://kubevirt.io/user-guide/contributing/ +- https://kubevirt.io/user-guide/release_notes/ +- `CONTRIBUTING.md`, `docs/contributing.md`, `docs/release_notes.md` + +## Additional context + +The maintainers must confirm the branch workflow first. Coordinate with #9019, which publishes versioned documentation, and #9020, which expands the contributor guide. + +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). diff --git a/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md new file mode 100644 index 00000000..f6b6ce36 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md @@ -0,0 +1,37 @@ +--- +title: Publish versioned documentation with a version selector #9019 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide publishes a single version of the documentation. A reader running an older KubeVirt release cannot find content for that release, and features such as v1.9 Beta-by-default behavior apply only to newer versions. Release branches already exist in the repository, but the site does not expose them. + +Publish versioned documentation with a version selector. Choose one approach: + +- Use `mike` with `extra.version.provider: mike` in `mkdocs.yml`, which adds the theme's version selector. +- Build each release branch and publish it under a `/vX.Y/` path. + +The result: + +- Publishes at least the supported N, N-1, and N-2 minor versions alongside `latest`. +- Shows a version selector in the header on every page. +- Redirects the unversioned URL to `latest`, so existing links keep working. + +Write a short design note in the pull request that compares the two approaches and explains how the publishing job in the project's CI changes. Ask the maintainers who owns the publishing pipeline and which versions are supported. + +## What you expected + +A reader selects their KubeVirt version from the header and sees the documentation for that release. Existing links to the unversioned site still resolve. + +## URL + +- https://kubevirt.io/user-guide/ +- `mkdocs.yml` and the publishing configuration for the guide + +## Additional context + +Depends on #9018, which documents the branch model that the versioned builds rely on. Until this issue is complete, the feature-state admonitions from #9017 stand in for versioning. The user guide is published beneath kubevirt.io, so confirm with the website maintainers that the `/vX.Y/` paths fit the website's routing (see #9045). + +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). diff --git a/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md b/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md new file mode 100644 index 00000000..f5d7edd5 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md @@ -0,0 +1,34 @@ +--- +title: Expand CONTRIBUTING.md into a documentation contributor guide #9020 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +`CONTRIBUTING.md` is a pointer to the Contributing page on the published site. The steps for building the guide live in `README.md`, and nothing in the repository describes the full path from an idea to a merged change. Contributors must guess the review process. + +Expand `CONTRIBUTING.md` into a documentation contributor guide that covers the full lifecycle: + +- How to propose a change: open an issue first or send a pull request directly. +- How to build and test locally. Move the build steps from `README.md` into this guide, and leave a link in `README.md`. +- What happens after you open a pull request: labels, the `/lgtm` and `/approve` commands, and the expected turnaround time. Ask the maintainers for the typical turnaround. +- When to add a redirect to `mkdocs.yml` and when to update `.nav.yml`. +- When a change needs a cherry-pick to a `release-vX.Y-stable` branch. + +Use the Thanos "How to contribute to docs" page as a model for structure and tone. Keep the Contributing page in `docs/contributing.md` as a short summary that links to the full guide. + +## What you expected + +A first-time contributor can go from a documentation idea to a merged pull request using only `CONTRIBUTING.md`, including how to build locally and what reviewers do. + +## URL + +- https://kubevirt.io/user-guide/contributing/ +- `CONTRIBUTING.md`, `README.md`, `docs/contributing.md` + +## Additional context + +The cherry-pick guidance depends on the branch model written in #9018, and the feature-state format from #9017 belongs in this guide too. Write the sections in a consistent order to avoid conflicts between the pull requests. + +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). diff --git a/analyses/2026/kubevirt/issues/9021-add-style-guide.md b/analyses/2026/kubevirt/issues/9021-add-style-guide.md new file mode 100644 index 00000000..b1bc3ad5 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9021-add-style-guide.md @@ -0,0 +1,36 @@ +--- +title: Add a documentation style guide #9021 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide has no written style guide. Contributors infer page structure, admonition use, code block format, and naming from existing pages, so pages drift apart and reviewers repeat the same feedback in every pull request. + +Add a short style guide, for example `docs/style_guide.md`, and add it to the Contributing section in `docs/.nav.yml`. Cover these topics, each with a one- or two-line rule and a short example: + +- Page structure: title, short concept paragraph, feature-state banner, procedure, related links. +- The standard feature-state admonition and when to use it. +- Code blocks: fenced blocks with a language tag, and no `$` prompts so readers can copy commands. +- Capitalization of Kubernetes objects, such as VirtualMachine, in UpperCamelCase. +- File naming under `docs/`. +- Minimizing language: avoid "simple", "simply", "easy", "easily", "just", and "obviously", and explain in one line that these words discourage readers who find the step difficult. + +Link the style guide from `CONTRIBUTING.md` and from the Contributing page. + +## What you expected + +A contributor can read one short page and learn how to structure and format a new page, including which words to avoid. Reviewers can point to the style guide instead of repeating the rules. + +## URL + +- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- `CONTRIBUTING.md` in the repository root +- `docs/.nav.yml` + +## Additional context + +Related: #9020 (expand `CONTRIBUTING.md`), #9022 (pull request template checklist), #9027 (reword existing minimizing language), and #9028 (automated language check). Ask the maintainers which feature-state banner wording is the standard so the guide documents the right one. + +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). diff --git a/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md b/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md new file mode 100644 index 00000000..b8841ed3 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md @@ -0,0 +1,35 @@ +--- +title: Add a pull request template #9022 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide repository has no pull request template, so authors do not see the checks that reviewers expect. Missing `.nav.yml` entries, missing redirects for moved pages, and missing feature-state banners then surface only in review. + +Add `.github/pull_request_template.md` with a short description prompt and a checklist: + +- The relevant `.nav.yml` is updated for every new page. +- A redirect is added to `mkdocs.yml` for every moved or renamed page. +- `make check_spelling` and `make check_links` pass. +- The feature-state banner is present on feature pages. +- The related kubevirt/kubevirt pull request or VEP (KubeVirt Enhancement Proposal) is linked. + +Keep the template under about 20 lines so authors actually read it. Check whether the Prow `release-note` block that kubevirt repositories use should also appear in the template. Ask the maintainers to confirm. + +## What you expected + +Every new pull request opens with the checklist pre-filled, and authors confirm each item before requesting review. + +## URL + +- Repository: https://github.com/kubevirt/user-guide +- New file: `.github/pull_request_template.md` +- Guide pages the checklist refers to: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) + +## Additional context + +Related: #9021 (style guide, which the checklist should link), #9020 (expanded `CONTRIBUTING.md`), and #9037 (first change walkthrough). Make the checklist wording match the commands those pages describe. + +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). diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md new file mode 100644 index 00000000..ef2561c2 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -0,0 +1,34 @@ +--- +title: Add per-directory OWNERS files #9023 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +All documentation reviews in the user guide route through the root `OWNERS` file. Pull requests on networking, storage, or compute pages therefore wait for general approvers instead of subject-matter experts, which adds to the open pull request backlog. + +Add `OWNERS` files in the topic directories and reference the existing aliases in `OWNERS_ALIASES`: + +- `docs/network/OWNERS` with the `sig-network-*` aliases. +- `docs/storage/OWNERS` with the `sig-storage-*` aliases. +- `docs/compute/OWNERS` with the `sig-compute-*` aliases. + +Keep the root `OWNERS` approvers for site-wide changes such as `mkdocs.yml` and `.nav.yml`. Use `reviewers` for the SIG aliases, and decide whether they should also be `approvers`. Verify the alias names against `OWNERS_ALIASES` before writing the files. If an alias does not exist, ask the maintainers whether to add it. + +## What you expected + +A pull request that changes only `docs/network/` requests review from networking experts, while root approvers still approve site-wide changes. + +## URL + +- Repository: https://github.com/kubevirt/user-guide +- `OWNERS` and `OWNERS_ALIASES` in the repository root +- New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` +- Guide sections: https://kubevirt.io/user-guide/network/, https://kubevirt.io/user-guide/storage/, https://kubevirt.io/user-guide/compute/ + +## Additional context + +Related: #9024 (a documentation reviewer role or SIG home) and #9026 (`MAINTAINERS.md` and emeritus review of `OWNERS_ALIASES`). Ask the maintainers whether SIG members want to receive documentation review requests. + +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). diff --git a/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md b/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md new file mode 100644 index 00000000..2fe1148a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md @@ -0,0 +1,37 @@ +--- +title: Give documentation a SIG home and clarify SIG meeting mechanics #9024 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Documentation has no clear organizational home. The `sig/documentation` entry in the community `sig-list.md` lacks chairs, a meeting cadence or async channel, and a charter. Newcomers cannot tell where to volunteer, and maintainers have no succession path. The SIG Storage charter has a "Meeting Mechanics" section, but it is unclear whether every SIG charter does. + +Open a pull request against kubevirt/community that does the following: + +- Populates the `sig/documentation` entry in `sig-list.md` with chairs, a meeting cadence or an async channel, and a charter covering both the user guide and the website. +- Records each SIG's meeting cadence and Slack channel in `sigs.yaml`, so the generated SIG list shows how to join every group. +- Adds a "Meeting Mechanics" section to each SIG charter that lacks one, modeled on the SIG Storage charter. + +## What you expected + +A newcomer can find the documentation group in the SIG list, see who leads it and when or where it meets, and find the same details for every other SIG in one generated list. + +## URL + +- SIG list: https://github.com/kubevirt/community/blob/main/sig-list.md +- `sigs.yaml` in https://github.com/kubevirt/community +- SIG charters in https://github.com/kubevirt/community + +## Additional context + +Questions for the maintainers: + +- Should documentation become its own SIG, or a working group under an existing SIG? +- Who volunteers as chair, and does the group meet or work asynchronously? +- Does every SIG charter already contain "Meeting Mechanics"? + +Related: #9023 (per-directory `OWNERS` files), #9026 (`MAINTAINERS.md` and maintainer ladder), and #9039 (triage cadence, which could run in the group's meeting). + +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). diff --git a/analyses/2026/kubevirt/issues/9025-triage-open-prs.md b/analyses/2026/kubevirt/issues/9025-triage-open-prs.md new file mode 100644 index 00000000..0c1e5a1d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9025-triage-open-prs.md @@ -0,0 +1,33 @@ +--- +title: Triage open pull requests and add a stale-PR policy #9025 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide repository has twelve open pull requests, some of them old. Contributors who open a pull request cannot tell how long review should take or what happens when a pull request goes quiet. + +Do the following: + +- Review each open pull request in https://github.com/kubevirt/user-guide/pulls. Merge, request changes, or close each one with a short comment. Start with the oldest. +- Add a "Stale pull requests" subsection to `CONTRIBUTING.md` that states the expected first-response time, when a pull request is marked stale, and when it closes. Align the wording with the Prow lifecycle labels (`lifecycle/stale`, `lifecycle/rotten`) the project already uses. +- Mirror the same text on the Contributing page. + +Ask the maintainers to confirm realistic turnaround times before publishing them. + +## What you expected + +No pull request older than the stated policy remains without a decision. Contributors read how long to wait for a review and what happens to inactive pull requests. + +## URL + +- Open pull requests: https://github.com/kubevirt/user-guide/pulls +- `CONTRIBUTING.md` in the repository root +- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) + +## Additional context + +Related: #9020 (expanded `CONTRIBUTING.md`, which should hold the policy), #9023 (`OWNERS` files to share review load), and #9024 (documentation reviewer role). + +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). diff --git a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md new file mode 100644 index 00000000..e9424da4 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -0,0 +1,33 @@ +--- +title: Add MAINTAINERS.md and a maintainer ladder #9026 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide does not say who its approvers are, who owns the release-notes script, or how a contributor becomes a reviewer or approver. `OWNERS_ALIASES` may also list people who are no longer active. The website repository already records dated emeritus entries. + +Make these changes in the user guide repository: + +- Add `MAINTAINERS.md` that names the user guide approvers, names the person or group responsible for the release-notes script, and says how to reach them. Alternatively, add a "Maintainers" section to the Contributing page. Model it on the NATS site `MAINTAINERS` file. +- Add a "Becoming a reviewer or approver" section to the README that describes the path from contributor to reviewer to approver, for example a number of merged documentation pull requests plus a nomination. Mirror the process in kubevirt/community for code SIGs. +- Review `OWNERS_ALIASES`, and move inactive people to dated emeritus entries as the website repository does. + +## What you expected + +A reader can find the current approvers and a contact, can see how to grow into the role, and can trust that the approver list reflects active people. + +## URL + +- Repository: https://github.com/kubevirt/user-guide (`OWNERS`, `OWNERS_ALIASES`, README) +- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- kubevirt/community membership policy: https://github.com/kubevirt/community/blob/main/membership_policy.md + +## Additional context + +Questions for the maintainers: Who should be listed as the release-notes script owner? How many merged pull requests should the ladder require? + +Related: #9023 (`OWNERS` files), #9024 (SIG home), and #9034 (the Contributing page should link `MAINTAINERS.md`). + +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). diff --git a/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md b/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md new file mode 100644 index 00000000..20e32baa --- /dev/null +++ b/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md @@ -0,0 +1,40 @@ +--- +title: Reword minimizing language and cancel terminology #9027 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Many pages use minimizing words such as "simply", "just", "of course", "obviously", "easy", and "easily". These words add nothing and can discourage readers who find a step difficult. The Live Migration page also says migrations "can be easily cancelled" without saying how, and uses "abort" where readers expect "cancel". + +Edit the pages with the most occurrences first: + +- `docs/compute/live_migration.md` +- `docs/user_workloads/windows_virtio_drivers.md` +- `docs/compute/node_assignment.md` +- `docs/compute/vsock.md` +- `docs/storage/disks_and_volumes.md` + +Delete the minimizing word where the sentence works without it. Replace "easy" or "easily" with what the step requires. For example, change "can be easily cancelled" to "can be cancelled by deleting the migration object". + +On the Live Migration page, prefer "cancel" in prose. Keep field names such as `Abort Requested` and `Abort Status` exactly as `kubectl` prints them. + +## What you expected + +The listed pages contain no minimizing words, and the Live Migration page uses "cancel" consistently in prose while still showing the real field names. + +## URL + +- https://kubevirt.io/user-guide/compute/live_migration/ +- https://kubevirt.io/user-guide/compute/windows_virtio_drivers/ +- https://kubevirt.io/user-guide/compute/node_assignment/ +- https://kubevirt.io/user-guide/storage/disks_and_volumes/ + +## Additional context + +Question for the API maintainers: Are the `Abort Requested` and `Abort Status` fields in the VirtualMachineInstanceMigration status candidates for a "cancel" alias in a future API version? + +Related: #9021 (style guide rule on minimizing language) and #9028 (automated check to prevent regressions). + +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). diff --git a/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md b/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md new file mode 100644 index 00000000..256191b3 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md @@ -0,0 +1,32 @@ +--- +title: Add accessibility and language checks to CI #9028 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The guide's pull request checks cover spelling (`make check_spelling`) and links, but nothing flags minimizing language or accessibility regressions such as low contrast. Both problems return unless a check catches them in the pull request. + +Add two checks to the `Makefile` and to the Prow pre-submit job: + +- A language check. Use Vale with the `write-good` style, or a grep-based target that runs next to `make check_spelling`. Flag "simple", "simply", "easy", "easily", "just", and "obviously". Start in warning mode if existing pages still contain matches. +- An accessibility check. Run `pa11y-ci` or Lighthouse against the built site for a sample of pages, for example the home page, Live Migration, and one storage page. + +Document both targets in the README and on the Contributing page. Prow job configuration lives in kubevirt/project-infra, so list the change needed there in this issue. + +## What you expected + +A pull request that introduces minimizing language or a contrast failure shows a failing or warning check before review. + +## URL + +- `Makefile` in https://github.com/kubevirt/user-guide +- Prow configuration: https://github.com/kubevirt/project-infra +- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) + +## Additional context + +Depends on #9027 (existing minimizing language must be fixed before the check can fail builds) and relates to #9048 (contrast fixes) and #9021 (style guide). Question for the maintainers: Should the Prow job block merges or only report warnings at first? + +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). diff --git a/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md b/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md new file mode 100644 index 00000000..61ff041b --- /dev/null +++ b/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md @@ -0,0 +1,38 @@ +--- +title: Fix legacy master links and the node-name example #9029 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The guide still uses the legacy `master` branch name in several places. + +- Fourteen links point to `kubevirt.io/api-reference/master/...`. Replace them with the `/main/` path, or with a versioned path such as `/v1.9.0/` where the page documents a specific release. Find them with `grep -rn "api-reference/master" docs`. The links appear in these files: + - `docs/compute/virtual_hardware.md` + - `docs/storage/disks_and_volumes.md` + - `docs/debug_virt_stack/debug.md` + - `docs/cluster_admin/migration_policies.md` + - `docs/cluster_admin/installation.md` + - `docs/cluster_admin/customize_components.md` + - `docs/network/interfaces_and_networks.md` +- `docs/user_workloads/presets.md` uses `kubevirt.io/nodeName: master` in an example. Replace the value with a neutral name such as `node01`, or remove the example, because the page documents a deprecated feature. +- Links to upstream projects such as libvirt, cri-tools, vhost-md, and kubevirt-ansible may also use a default branch name that those projects have since changed. Prefer tagged or permalink URLs for them so the branch name does not appear in the guide. + +Run `make check_links` after the edits. + +## What you expected + +No link or example in the guide uses `master` as a branch or node name, and all edited links resolve. + +## URL + +- https://kubevirt.io/user-guide/user_workloads/presets/ (`docs/user_workloads/presets.md`) +- https://kubevirt.io/user-guide/cluster_admin/installation/ (`docs/cluster_admin/installation.md`) +- Other files listed above under `docs/` + +## Additional context + +Question for the maintainers: Should API reference links track `/main/` or the latest released version? + +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). diff --git a/analyses/2026/kubevirt/issues/9030-add-community-page.md b/analyses/2026/kubevirt/issues/9030-add-community-page.md new file mode 100644 index 00000000..45e21020 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9030-add-community-page.md @@ -0,0 +1,35 @@ +--- +title: Add a Community and communication page to the guide #9030 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Community channels appear only in the "Getting help" list on the Welcome page. A reader who stays in the guide can miss the Slack channels, the mailing list, community meetings, and social accounts. + +Add a "Community and communication" page, for example `docs/community.md`, and add it to `docs/.nav.yml`. Include: + +- Channels, each with a one-line purpose: `#virtualization` on Kubernetes Slack for usage questions, `#kubevirt-dev` for contributor discussion, and the kubevirt-dev mailing list for announcements and longer threads. +- Social accounts. +- Community meetings: state the cadence, list the meeting times, and link the public calendar (`kubevirt@cncf.io`) so readers can join without leaving the guide. + +Keep the content consistent with the kubevirt.io Community page. Link to that page for governance, and avoid copying content that will go out of date. + +## What you expected + +A reader finds every community channel and how to join a meeting in one guide page, and the information matches the kubevirt.io Community page. + +## URL + +- Welcome page: https://kubevirt.io/user-guide/ (`docs/index.md`) +- Community page: https://kubevirt.io/community/ +- New file: `docs/community.md`; navigation in `docs/.nav.yml` + +## Additional context + +Question for the maintainers: Which source is authoritative for meeting times, the guide, the Community page, or the shared calendar? Prefer linking the calendar to avoid stale times. + +Related: #9031 (Community and adoption block on the index page), #9032 (footer links), #9035 (where to ask for help), and #9040 (Governance section on the Community 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). diff --git a/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md b/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md new file mode 100644 index 00000000..ca43bb98 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md @@ -0,0 +1,34 @@ +--- +title: Add a Community and adoption block to the index and Contributing page #9031 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Readers of the guide get no pointer to the wider KubeVirt community or to evidence of adoption. The Contributing page invites readers to submit case studies, but does not show them what a case study looks like. + +Make these changes: + +- Add a short "Community and adoption" block to `docs/index.md` with links to the kubevirt.io blog, videos, KubeVirt Summit, the adopters or case-studies page, and Slack. +- Optionally add a top-level "Community" entry to `docs/.nav.yml` that opens the kubevirt.io Community page. +- In `docs/contributing.md`, link to the existing adopters list and case studies next to the invitation to submit one, so contributors can see the format to follow. + +Verify each target URL before linking and run `make check_links`. + +## What you expected + +A reader on the Welcome page finds the blog, videos, Summit, adopters, and Slack in one block. A case-study contributor sees existing examples before writing their own. + +## URL + +- https://kubevirt.io/user-guide/ (`docs/index.md`) +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- `docs/.nav.yml` +- https://kubevirt.io/community/ + +## Additional context + +Related: #9030 (Community and communication page in the guide, which the "Community" entry could use instead of an external link), #9032 (footer links), and #9034 through #9037 (other changes to the Contributing page; coordinate edits to avoid merge conflicts). + +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). diff --git a/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md b/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md new file mode 100644 index 00000000..bc01fcc1 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md @@ -0,0 +1,31 @@ +--- +title: Add repository and social links to the footer #9032 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The guide's header and footer give no link to the repository, Slack, the mailing list, or the main kubevirt.io site. These links appear only in the "Getting help" list on the Welcome page. `mkdocs.yml` sets neither `repo_url` nor an `extra.social` block. + +Edit `mkdocs.yml`: + +- Set `repo_url` to `https://github.com/kubevirt/user-guide`. Also set `repo_name` if the default label is unclear. Check that the Material theme shows the repository link in the header. +- Add an `extra.social` block with icons and links for GitHub, Slack, the mailing list, and `kubevirt.io`. + +Run `mkdocs serve` locally and confirm the links render on every page, in light and dark mode. + +## What you expected + +Every page shows the repository link in the header and the GitHub, Slack, mailing list, and kubevirt.io links in the footer. + +## URL + +- https://kubevirt.io/user-guide/ (any page footer) +- `mkdocs.yml` in https://github.com/kubevirt/user-guide + +## Additional context + +Related: #9046 (other user guide footer compliance fixes in `mkdocs.yml`, such as the `copyright` line), #9030 (Community page), and #9047 (website footer). Combine the `mkdocs.yml` edits with #9046 if the same contributor takes both. + +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). diff --git a/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md b/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md new file mode 100644 index 00000000..3d708e77 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md @@ -0,0 +1,30 @@ +--- +title: Fix logo alt text and remove unused assets and config #9033 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Three small problems affect the guide's branding and repository hygiene. + +- **Logo alt text.** The header logo has no useful alternative text, so screen readers cannot name it. Set the alt text to "KubeVirt" by adding `extra.homepage` or a custom `partials/logo.html` override in the theme overrides. +- **Unused legacy assets.** Delete `asciibinder-logo-horizontal.png`, `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. Confirm with `grep -rn` that nothing references them first. +- **Unsupported config key.** Remove the top-level `site_favicon: assets/favicon.ico` key from `mkdocs.yml`. MkDocs ignores it, and the active favicon is already set under `theme.favicon`. + +Build the site and confirm the logo, favicon, and pages still render. + +## What you expected + +The header logo reads as "KubeVirt" to a screen reader, `docs/assets` contains only current brand assets, and `mkdocs.yml` has no ignored keys. + +## URL + +- https://kubevirt.io/user-guide/ (header logo) +- `docs/assets/` and `mkdocs.yml` in https://github.com/kubevirt/user-guide + +## Additional context + +Related: #9049 (table captions and Architecture diagram, covering the other accessibility fixes) and #9048 (contrast). The `theme.favicon` setting should stay as is. + +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). diff --git a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md new file mode 100644 index 00000000..6d7f68c5 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -0,0 +1,30 @@ +--- +title: Add a project overview and resource descriptions to the Contributing page #9034 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Contributing page sends newcomers to a list of community resources without describing them or explaining how KubeVirt is run. A newcomer cannot tell which link answers their question. + +Edit `docs/contributing.md`: + +- Add a short "How the project is run" paragraph above the resource list. Name the maintainer group, explain that work is organized in SIGs (special interest groups), and state that decisions default to lazy consensus. +- Add a one-sentence description to each link in "Important community resources" that says what the reader finds there. +- Add links to the kubevirt/community resources a newcomer needs: the SIG list, the help-wanted guide, the community meeting document, and the maintainers list (`MAINTAINERS.md`). + +## What you expected + +A newcomer understands the project structure before following links, and each link states what it leads to. + +## URL + +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- https://github.com/kubevirt/community (`sig-list.md`, `GOVERNANCE.md`, `MAINTAINERS.md`) + +## Additional context + +Related: #9035, #9036, and #9037 (other additions to the same page; coordinate to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 (governance text on the Community page, which should use the same wording), and #9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list should the page link, the community one or a user guide one? + +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). diff --git a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md new file mode 100644 index 00000000..08372f4b --- /dev/null +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -0,0 +1,32 @@ +--- +title: Add where-to-ask-help and the VEP docs deadline to the Contributing page #9035 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Contributing page does not say where contributors can ask questions, whether mentoring exists, or when documentation for a new feature is due. + +Edit `docs/contributing.md` and repeat the help section in `CONTRIBUTING.md`: + +- Add a "Where to ask for help" section. Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and `#virtualization` for usage questions. Link the Slack invitation page. State that the weekly community meeting includes newcomer introductions, with the day, time, and Zoom link. Name the documentation approvers or a docs contact. +- State that the VEP (KubeVirt Enhancement Proposal) checklist requires the documentation pull request to be merged by code freeze. Link the VEP process. +- Add a short note on mentoring. The help-wanted guide promises "extra assistance" on `good first issue` items, so state how to request it. + +## What you expected + +A first-time contributor knows where to ask, when to join a meeting, whom to contact, and by when feature documentation must merge. + +## URL + +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- `CONTRIBUTING.md` in https://github.com/kubevirt/user-guide + +## Additional context + +Questions for the maintainers: Does a mentoring or buddy arrangement for first-time contributors exist, or could one be offered? If not, remove the mentoring note. Who is the docs contact? + +Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), #9034, #9036, #9037 (same page), and #9020. + +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). diff --git a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md new file mode 100644 index 00000000..c62e63a4 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -0,0 +1,32 @@ +--- +title: Link filtered issue lists and explain labels on the Contributing page #9036 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Contributing page gives generic advice to look for `good-first-issue` items. It does not link to a filtered list, and it does not explain how `good first issue` differs from `help wanted`. + +Edit `docs/contributing.md`: + +- Replace the generic advice with a direct link to the filtered issue list for each repository where newcomers can work, for example kubevirt/user-guide, kubevirt/kubevirt, and kubevirt/kubevirt.github.io. +- Add a short explanation of both labels. Use `good first issue` for small, self-contained tasks and `help wanted` for slightly larger but still approachable tasks. +- Link the help-wanted guide in kubevirt/community. + +Where `help wanted` is not applied consistently in a repository, note that in this issue so maintainers can label a few issues. + +## What you expected + +A newcomer clicks one link per repository and sees a current list of beginner-friendly issues, and knows what each label means. + +## URL + +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- https://github.com/kubevirt/user-guide/issues + +## Additional context + +Depends on #9038 (the label name must be standardized before linking the filter) and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, #9037. + +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). diff --git a/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md b/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md new file mode 100644 index 00000000..cedff7e8 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md @@ -0,0 +1,31 @@ +--- +title: Add a first documentation change walkthrough to the Contributing page #9037 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Contributing page does not walk a newcomer through making a documentation change, and the build and test steps live only in the repository README. Code-minded newcomers also get a single link instead of a next step. + +Edit `docs/contributing.md`: + +- Add a "Making your first documentation change" section that covers these steps: find or file an issue; comment to claim it; fork and branch; edit under `docs/` and update `.nav.yml`; run `make check_spelling` and `make check_links`; sign off with `git commit -s`; open the pull request; and what to expect from Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. +- Move the build and test steps from the README into this section, or link to them prominently. +- Add a "Contributing to the code" subsection that summarizes the kubevirt/kubevirt path in three or four steps: read `CONTRIBUTING.md`, follow `docs/getting-started.md` in kubevirt/kubevirt to build and run a local cluster, pick an issue, and open a draft pull request. + +## What you expected + +A newcomer completes a first documentation pull request using only this page, and a code-minded newcomer sees a short path into kubevirt/kubevirt. + +## URL + +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- README in https://github.com/kubevirt/user-guide +- https://github.com/kubevirt/kubevirt/blob/main/docs/getting-started.md + +## Additional context + +Related: #9020 (the same lifecycle in `CONTRIBUTING.md`; keep the two consistent or have one link the other), #9022 (pull request template), #9021 (style guide), and #9034 through #9036 (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). diff --git a/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md b/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md new file mode 100644 index 00000000..e3418072 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md @@ -0,0 +1,34 @@ +--- +title: Standardize the good first issue label #9038 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +KubeVirt repositories carry two near-duplicate labels, the hyphenated `good-first-issue` and the GitHub-native `good first issue`. Issues with the hyphenated label do not appear in GitHub's "Contribute" tab or in good-first-issue discovery tooling, so newcomers cannot find them. Prow can also auto-close still-relevant issues that reach `lifecycle/rotten`. + +Do the following: + +- Choose the GitHub-native `good first issue` (spaced) as the standard label. +- In each repository that has both labels, re-label issues from `good-first-issue` to `good first issue`, then retire the hyphenated label or alias it in the label configuration. +- Update the label reference on the Contributing page and in `CONTRIBUTING.md`. +- Apply `lifecycle/frozen`, or triage promptly, for still-relevant enhancements and documentation requests so they do not close for inactivity alone. + +## What you expected + +Each repository has one `good first issue` label, beginner issues appear in GitHub's Contribute tab, and the Contributing page names the same label. + +## URL + +- https://github.com/kubevirt/user-guide/labels +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- `CONTRIBUTING.md` in https://github.com/kubevirt/user-guide + +## Additional context + +Question for the maintainers: Is label configuration managed centrally, for example in kubevirt/project-infra, so the change belongs there? + +Related: #9036 (filtered issue links depend on this label) and #9039 (backlog triage). + +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). diff --git a/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md b/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md new file mode 100644 index 00000000..400c203d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md @@ -0,0 +1,32 @@ +--- +title: Triage the issue backlog and publish a triage cadence #9039 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide's open issues are largely unlabeled, and few if any are suitable for newcomers. Without labels and a regular triage routine, contributors cannot tell which issues are ready to work on. + +Do the following: + +- Triage the open backlog in https://github.com/kubevirt/user-guide/issues. Apply `kind/*` and `sig/documentation` labels to unlabeled issues, and apply `triage/accepted` to issues that are ready to be worked on. +- File a small, steady pool of beginner issues for documentation gaps, typos, and small feature-doc updates, and label them `good first issue`. +- Add a short "good first issue" checklist to the org-level issue templates: affected page, expected outcome, and pointers to relevant docs. Keep using the existing templates. +- Publish a lightweight triage cadence, for example a periodic documentation-issue triage during a SIG or community meeting, in `CONTRIBUTING.md` and on the Contributing page. State who labels, who accepts, and how staleness is handled. + +## What you expected + +Every open issue has a `kind/*` label and a triage state, at least a few `good first issue` items are always open, and contributors can read how often triage happens. + +## URL + +- https://github.com/kubevirt/user-guide/issues +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- Issue templates in the kubevirt organization `.github` repository + +## Additional context + +Questions for the maintainers: Which meeting could host triage, and who owns it? Related: #9038 (label standardization), #9036 (issue list links), #9024 (SIG home), and #9025 (pull request triage). Do #9038 first. + +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). diff --git a/analyses/2026/kubevirt/issues/9040-add-governance-section.md b/analyses/2026/kubevirt/issues/9040-add-governance-section.md new file mode 100644 index 00000000..a4099591 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9040-add-governance-section.md @@ -0,0 +1,32 @@ +--- +title: Add a Governance section to the kubevirt.io Community page #9040 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The kubevirt.io Community page does not explain how the project is governed. Governance documents exist in kubevirt/community, but a visitor to the Community page has no summary and no links. + +Open a pull request against the kubevirt.io website repository (kubevirt/kubevirt.github.io) that adds a "Governance" section to the Community page: + +- Write two or three sentences that state how KubeVirt is governed: a CNCF incubating project, run by a maintainer group, organized in SIGs and working groups, with lazy consensus and maintainer votes for decisions. +- Link `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in kubevirt/community. + +Verify each link target before publishing, and use the same wording as the "How the project is run" paragraph on the Contributing page. + +## What you expected + +A visitor to the Community page reads how KubeVirt is governed in under a minute and reaches each governance document in one click. + +## URL + +- https://kubevirt.io/community/ +- https://github.com/kubevirt/community (`GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, `sig-list.md`) +- https://github.com/kubevirt/kubevirt.github.io + +## Additional context + +Related: #9034 (Contributing page overview, same wording), #9030 (Community page in the guide), and #9024 (SIG list). Question for the maintainers: Is the project still described as CNCF incubating, and do maintainer votes apply to all decisions? + +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). diff --git a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md new file mode 100644 index 00000000..7cf49059 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md @@ -0,0 +1,40 @@ +--- +title: Document where documentation lives #9041 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +KubeVirt documentation is spread across `kubevirt/user-guide`, `kubevirt/kubevirt.github.io`, and `kubevirt/kubevirt/docs`. No repository states which kind of content belongs where, so contributors cannot tell where to add a new page and similar content ends up in more than one place. + +Add a short "Where documentation lives" section to the README of each of these repositories: + +- `kubevirt/user-guide` +- `kubevirt/kubevirt.github.io` +- `kubevirt/kubevirt` + +Use the same text in all three. The section states that: + +- User and operator documentation belongs in the user guide. +- Marketing, blog, and community content belongs on the website. +- `kubevirt/kubevirt/docs` is for design and developer notes only. + +Then link to the new section from `docs/contributing.md` in the user guide, for example from the "Other ways to contribute" section. + +## What you expected + +A contributor can read one short section in any of the three repositories and know which repository to use for a new page. The Contributing page links to that guidance. + +## URL + +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- https://github.com/kubevirt/user-guide/blob/main/README.md +- https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md +- https://github.com/kubevirt/kubevirt/blob/main/README.md + +## Additional context + +Related: #9060 adds a "Site infrastructure" section to the same READMEs, so coordinate the edits. Related: #9043 and #9044 act on the boundary this issue documents. + +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). diff --git a/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md b/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md new file mode 100644 index 00000000..8e3269f8 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md @@ -0,0 +1,31 @@ +--- +title: Add an API reference entry to the guide navigation #9042 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The KubeVirt API reference is published from a separate repository (`kubevirt/kubevirt.github.io`, at `kubevirt.github.io/api-reference`). The user guide navigation has no entry for it, so readers who need field-level details of a VirtualMachine or other API object must already know it exists. + +Make the API reference visible from the guide: + +- Add an "API Reference" entry to `docs/.nav.yml` that links directly to `https://kubevirt.github.io/api-reference/`, or add a short landing page, for example `docs/api_reference.md`, and list it in `docs/.nav.yml`. +- If you add a landing page, explain that the reference is generated from the API types and published separately, link to it, and explain which API version it covers. Ask the maintainers whether the reference tracks `main` or the latest release, and state the answer on the page. +- Check that the awesome-nav plugin renders the external link and that it opens correctly. + +## What you expected + +A reader browsing the guide navigation sees an API reference entry and reaches the reference in one click, without knowing which repository publishes it. + +## URL + +- https://kubevirt.io/user-guide/ +- `docs/.nav.yml` +- https://kubevirt.github.io/api-reference/ + +## Additional context + +Related: #9041 documents which repository owns which content, and #9059 covers search across the guide and the website. + +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). diff --git a/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md b/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md new file mode 100644 index 00000000..78b0d591 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md @@ -0,0 +1,34 @@ +--- +title: Audit kubevirt/kubevirt docs for user-facing content #9043 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The `docs/` directory in `kubevirt/kubevirt` contains pages that the user guide links to instead of hosting itself. Readers who follow those links leave the guide, lose its navigation and search, and read content that may not be maintained for end users. + +Audit the `kubevirt/kubevirt` repository and consolidate user-facing content in the guide: + +1. Start with the files the user guide already links to: `getting-started.md`, `architecture.md`, and `cloud-init.md`. +2. For each file, decide whether it is user-facing or a design or developer note. +3. Move the user-facing portions into the matching pages in `kubevirt/user-guide`, for example `docs/architecture/architecture.md` and the cloud-init page under `docs/user_workloads/`. +4. Replace each original file in `kubevirt/kubevirt` with a one-line pointer to the new guide page so search results and old links still resolve. +5. Update the user guide links that point at the old files. + +Open the pull requests in both repositories. Ask the maintainers whether a file that mixes user and developer content should be split or left in place. + +## What you expected + +The guide hosts the user-facing content for these three topics, and the files in `kubevirt/kubevirt/docs` point readers to the guide. + +## URL + +- https://kubevirt.io/user-guide/architecture/architecture/ (`docs/architecture/architecture.md`) +- https://github.com/kubevirt/kubevirt/tree/main/docs + +## Additional context + +Depends on the content boundary decision in #9041. Related: #9044 applies the same audit to the CDI documentation. + +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). diff --git a/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md b/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md new file mode 100644 index 00000000..1f809675 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md @@ -0,0 +1,31 @@ +--- +title: Audit CDI documentation for storage pages #9044 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Six pages in the guide's storage content link out to the `doc/` directory of the Containerized Data Importer (CDI) repository, `kubevirt/containerized-data-importer`. Readers lose the guide's navigation and search when they follow those links, and the guide never explains why this content lives elsewhere. + +Triage the CDI pages that the guide links to and pick one outcome for each page: + +- Move the page into the guide's `docs/storage/` section and add it to `docs/storage/.nav.yml`, leaving a one-line pointer in the CDI repository. +- Keep the page in CDI and list it on a new "CDI reference documentation" page in `docs/storage/`. The page explains why the remaining CDI content stays in its own repository and links each page with a one-sentence summary. + +Start by listing the six storage pages with their CDI links, for example in `docs/storage/containerized_data_importer.md`. Ask the CDI maintainers which pages they prefer to keep. + +## What you expected + +Every CDI link in the storage section either leads to a page hosted in the guide or to a clearly described reference page that explains why the content lives in the CDI repository. + +## URL + +- https://kubevirt.io/user-guide/storage/containerized_data_importer/ (`docs/storage/containerized_data_importer.md`) +- https://github.com/kubevirt/containerized-data-importer/tree/main/doc + +## Additional context + +Depends on the content boundary decision in #9041. Related: #9043 applies the same audit to `kubevirt/kubevirt/docs`. + +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). diff --git a/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md b/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md new file mode 100644 index 00000000..6edbac56 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md @@ -0,0 +1,33 @@ +--- +title: Decide whether to converge the website and user guide #9045 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide is built with MkDocs and Material for MkDocs, and the main website (`kubevirt/kubevirt.github.io`) is built with Jekyll. The two sites have different generators, themes, and maintenance skills. This split makes search, navigation, branding, and analytics harder to keep consistent, and no document records whether it is intentional. + +Run a short evaluation and record the decision in a written decision record, for example a comment on this issue or a page in `kubevirt/community`: + +- Compare the cost of three options: keep both toolchains, move the website pages into the user guide repository, or bring the guide into the website repository as a Git submodule. +- Evaluate moving the website to Material for MkDocs or another generator with a supported theme, such as Hugo or Docusaurus, so one skill set covers both sites. +- List the maintainers who must agree. + +If the sites stay separate, add a short note to the README of both repositories that states the reasons (different generators, maintainers, and audiences). If the project plans to converge, keep this issue open as the tracking issue even when the migration is deferred. + +## What you expected + +The decision about the two toolchains is recorded, with reasons, and both READMEs reflect it. + +## URL + +- https://github.com/kubevirt/user-guide/blob/main/README.md +- https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md +- https://kubevirt.io/user-guide/ + +## Additional context + +Related: #9060 documents site infrastructure ownership in the same READMEs. Related: #9059 (unified search) and #9052 (brand reference) become simpler if the sites converge. + +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). diff --git a/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md b/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md new file mode 100644 index 00000000..a406d1e3 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md @@ -0,0 +1,34 @@ +--- +title: Bring the user guide footer into compliance #9046 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide footer does not carry the copyright, CNCF, and trademark text that the main website footer shows. The two properties therefore read as separate projects, and the guide lacks the legal links the project footer should include. + +Update the guide footer in `kubevirt/user-guide`: + +- Set `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"` in `mkdocs.yml`. +- Add `overrides/partials/copyright.html` (or a `footer.html` override) and set `theme.custom_dir: overrides` in `mkdocs.yml`. +- In the override, append the sentence "We are a Cloud Native Computing Foundation incubating project", the CNCF logo linked to `https://www.cncf.io`, and a link to `https://lfprojects.org/policies/` for trademark and terms. +- Copy the wording and links from `_includes/footer.html` in `kubevirt/kubevirt.github.io` so both footers match. + +Build the site locally with `mkdocs serve` and check the footer in both the light and dark schemes. + +## What you expected + +Every guide page shows the same copyright line, CNCF statement and logo, and LF Projects policies link as the main website. + +## URL + +- https://kubevirt.io/user-guide/ (footer on every page) +- `mkdocs.yml` +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_includes/footer.html + +## Additional context + +Related: #9047 fixes the website footer, and #9032 adds repository and social links to the guide footer. Edit the same override file in both issues. + +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). diff --git a/analyses/2026/kubevirt/issues/9047-fix-website-footer.md b/analyses/2026/kubevirt/issues/9047-fix-website-footer.md new file mode 100644 index 00000000..59623ed2 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9047-fix-website-footer.md @@ -0,0 +1,32 @@ +--- +title: Fix the website footer and add community health files #9047 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +This issue affects `kubevirt/kubevirt.github.io` (the main website) and `kubevirt/user-guide`. The website copyright line omits the © symbol, the two repositories lack a root `CODE_OF_CONDUCT.md`, and the website repository has no `CONTRIBUTING.md`. The maturity statement in each footer also has no owner and can go stale when the CNCF status changes. + +Make these changes: + +1. In `_includes/footer.html` of `kubevirt/kubevirt.github.io`, change the copyright line to "Copyright © KubeVirt a Series of LF Projects, LLC". +2. Add a root `CODE_OF_CONDUCT.md` to both `kubevirt/user-guide` and `kubevirt/kubevirt.github.io` that links to the code of conduct in `kubevirt/community`. +3. Add a `CONTRIBUTING.md` to `kubevirt/kubevirt.github.io` that points to the contributing content in its README and to the user guide Contributing page. +4. Add a note to each repository's README that names the footer file to edit when the project's CNCF maturity level changes: `_includes/footer.html` for the website and the footer override for the guide. + +## What you expected + +Both repositories contain the community health files, the website footer shows the © symbol, and a maintainer can find where to update the maturity statement. + +## URL + +- https://kubevirt.io/ (footer) +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_includes/footer.html +- https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) + +## Additional context + +Related: #9046 updates the user guide footer. Add the maturity note to the guide README only after #9046 creates the footer override. + +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). diff --git a/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md b/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md new file mode 100644 index 00000000..fae4c6ba --- /dev/null +++ b/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md @@ -0,0 +1,31 @@ +--- +title: Fix header and link contrast and align brand colors #9048 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The guide uses the teal `#0db2b6` as `--md-primary-fg-color` in `docs/stylesheets/extra.css`. White header and tab text on this teal falls below the 4.5:1 contrast ratio that WCAG AA requires. Links also rely on a `filter: brightness(80%)` rule rather than explicit colors. In addition, `#0db2b6` does not appear in the `$kv-color--green-*` scale that the main website documents, so the two sites use different greens. + +Update `docs/stylesheets/extra.css`: + +- Darken `--md-primary-fg-color` to a teal with at least 4.5:1 contrast against white (for example `#007a7e` or darker), or keep the brand teal for decorative elements and set the header and tab text to a dark foreground. +- Replace the `filter: brightness(80%)` rule with explicit `--md-typeset-a-color` values for the light and dark schemes, each with at least 4.5:1 contrast. +- Choose the final color from the documented website scale (for example `$kv-color--green-300`, `#00aab2`), or ask the website maintainers whether to add `#0db2b6` to the scale. +- Check both schemes with a contrast checker and record the ratios in the pull request. + +## What you expected + +Header text, tab text, and links meet 4.5:1 contrast in both color schemes, and the guide draws its primary color from the same scale as the website. + +## URL + +- https://kubevirt.io/user-guide/ (header, tabs, and body links) +- `docs/stylesheets/extra.css` + +## Additional context + +Related: #9052 publishes the brand reference that lists the canonical color scale. + +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). diff --git a/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md b/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md new file mode 100644 index 00000000..89ab2f7a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md @@ -0,0 +1,39 @@ +--- +title: Fix mobile tables and replace the Architecture diagram #9049 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Wide tables and the Architecture page diagram do not work well on phones and with screen readers. + +### Tables + +`docs/stylesheets/extra.css` contains a `display: table; width: max-content` override. Check on a phone whether the tables in the Arm64 feature-gate status and device status pages scroll horizontally or overflow the page. If they overflow, remove the override or scope it to specific tables with an `attr_list` class. Then add a short sentence above each wide status table that states what the table shows. + +### Architecture diagram + +The Architecture page shows the stack as an ASCII diagram, which screen readers read as noise and phones wrap badly. Replace it with one of these: + +- An image with descriptive alt text. +- A Mermaid diagram. Enable it by adding a `mermaid` custom fence to the existing `pymdownx.superfences` entry in `mkdocs.yml`. + +Add a one-paragraph prose description of the layers below the diagram so every reader gets the same information. + +## What you expected + +Tables scroll inside the page on a phone, each wide table has an introductory sentence, and the Architecture page presents the stack as an accessible diagram with a prose description. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/feature_gate_status_on_Arm64/ (`docs/cluster_admin/feature_gate_status_on_Arm64.md`) +- https://kubevirt.io/user-guide/cluster_admin/device_status_on_Arm64/ (`docs/cluster_admin/device_status_on_Arm64.md`) +- https://kubevirt.io/user-guide/architecture/architecture/ (`docs/architecture/architecture.md`) +- `docs/stylesheets/extra.css`, `mkdocs.yml` + +## Additional context + +Related: #9033 fixes the logo alt text, and #9048 also edits `docs/stylesheets/extra.css`. + +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). diff --git a/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md b/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md new file mode 100644 index 00000000..f3ea1965 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md @@ -0,0 +1,36 @@ +--- +title: Split the Disks and Volumes and Interfaces and Networks pages #9050 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Two guide pages are far longer than readers can scan. `docs/storage/disks_and_volumes.md` runs to about 2,160 lines and `docs/network/interfaces_and_networks.md` to about 900 lines. Readers have to scroll through a long right-hand table of contents to find one volume type or binding method, and links to sections break when headings change. + +Split both pages into sub-pages: + +- **Disks and Volumes:** keep an overview page with the disk and volume concepts and a table linking to one sub-page per volume type, for example `docs/storage/volumes/`. +- **Interfaces and Networks:** separate the interface binding methods from the network attachment content, each in its own page, and keep an overview page that links to both. + +For each split: + +1. Move the content without rewriting it. +2. Update `docs/storage/.nav.yml` and `docs/network/.nav.yml`. +3. Add an entry to the `redirects` map in `mkdocs.yml` for any moved anchor or page so existing links keep working. +4. Fix internal links with `grep` for the old paths. + +## What you expected + +Each resulting page is a manageable length, the overview pages guide readers to the right sub-page, and existing URLs keep resolving. + +## URL + +- https://kubevirt.io/user-guide/storage/disks_and_volumes/ (`docs/storage/disks_and_volumes.md`) +- https://kubevirt.io/user-guide/network/interfaces_and_networks/ (`docs/network/interfaces_and_networks.md`) + +## Additional context + +Related: #9051 splits the Live Migration and Release Notes pages, and #9009 adds landing pages to the Storage and Network sections. Coordinate navigation edits with those issues. + +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). diff --git a/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md b/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md new file mode 100644 index 00000000..e14f6db9 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md @@ -0,0 +1,39 @@ +--- +title: Split the Live Migration and Release Notes pages #9051 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +`docs/compute/live_migration.md` has about 650 lines and `docs/release_notes.md` has about 3,050 lines. Both are too long to navigate, and the Release Notes tab opens at the top of the page, which is the oldest-first or the longest scroll for readers who want the newest release. + +### Live Migration + +Keep the overview and basic procedure on the Live Migration page. Move the migration strategies and the migration network configuration to sub-pages under `docs/compute/` and link them from the overview. + +### Release Notes + +Split the page into one page per minor release, or paginate it. Create an index page that lists the releases newest first. Set the Release Notes tab in `docs/.nav.yml` so it opens the newest release. + +For both pages: + +1. Move the content without rewriting it. +2. Update `docs/compute/.nav.yml` and `docs/.nav.yml`. +3. Add old paths and anchors to the `redirects` map in `mkdocs.yml`. +4. Fix internal links to the moved sections. + +## What you expected + +Each page is a manageable length, the Release Notes tab opens the newest release, and existing links still resolve. + +## URL + +- https://kubevirt.io/user-guide/compute/live_migration/ (`docs/compute/live_migration.md`) +- https://kubevirt.io/user-guide/release_notes/ (`docs/release_notes.md`) + +## Additional context + +Related: #9050 splits the Disks and Volumes and Interfaces and Networks pages, and #9008 changes where Release Notes sits in the navigation. Coordinate `docs/.nav.yml` edits with #9008. + +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). diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md new file mode 100644 index 00000000..f52c2018 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -0,0 +1,33 @@ +--- +title: Publish a brand reference #9052 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The brand assets of KubeVirt live in several places. The website defines a `$kv-color--green-*` scale, and the user guide uses its own colors in `docs/stylesheets/extra.css`. No single page lists the canonical logo files, colors, and typefaces, so the two sites drift apart when the palette changes. + +Publish a short brand reference in either `kubevirt/kubevirt.github.io` or `kubevirt/community`. Ask the maintainers which repository is the better home. The reference lists: + +- The canonical logo files: the icon and the horizontal wordmark, with links to the files. +- The hex values of the `$kv-color--green-*` scale. +- The approved typefaces. + +Then add a comment at the top of `docs/stylesheets/extra.css` in the user guide that cites the reference URL and tells editors to update the guide when the palette changes. + +## What you expected + +One page is the source of truth for logos, colors, and typefaces, and the guide stylesheet points to it. + +## URL + +- `docs/stylesheets/extra.css` +- https://kubevirt.io/user-guide/ (header logo and colors) +- https://github.com/kubevirt/kubevirt.github.io (website styles and assets) + +## Additional context + +Related: #9048 aligns the guide's primary color with the website scale, and #9033 fixes the logo alt text. Complete #9048 first so the reference lists the final values. + +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). diff --git a/analyses/2026/kubevirt/issues/9053-add-adopters-page.md b/analyses/2026/kubevirt/issues/9053-add-adopters-page.md new file mode 100644 index 00000000..7a8e6213 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9053-add-adopters-page.md @@ -0,0 +1,32 @@ +--- +title: Add an adopters page and link CNCF case studies #9053 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +This issue affects the main website, `kubevirt/kubevirt.github.io`. KubeVirt has two published CNCF case studies (NTT Docomo Business and Swisscom), but `kubevirt.io` does not link to them. The landing page shows an End Users logo wall, and evaluators have no single page that shows adoption evidence. + +Make two changes in `kubevirt/kubevirt.github.io`: + +1. Add a "Case Studies" block beneath the End Users logo wall on the landing page that links to the two CNCF case studies. The content already exists, so this change needs no new writing. +2. Create an `/adopters/` (or `/case-studies/`) page that renders the full adopters table with the columns type, name, since, and use case, and links to the CNCF case studies. Add the page to `_data/site_nav_pages.yml`. + +Build the table from `_data/adopters.yml`, which the website already generates from `ADOPTERS.md`, rather than copying data by hand. + +## What you expected + +An evaluator reaches the two case studies from the landing page and finds all adopters on one page that is listed in the site navigation. + +## URL + +- https://kubevirt.io/ (End Users logo wall) +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/site_nav_pages.yml +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/adopters.yml + +## Additional context + +Related: #9054 adds the use-case text and KubeVirt-specific vendor links to the same data and 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). diff --git a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md new file mode 100644 index 00000000..a2853e02 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -0,0 +1,34 @@ +--- +title: Show adopter use cases and KubeVirt-specific vendor links #9054 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +This issue affects the main website, `kubevirt/kubevirt.github.io`. The adopters logo wall shows only logos. The "Use-Case" text that each adopter supplies in `ADOPTERS.md` never reaches the site, and vendor logos link to corporate homepages that do not mention KubeVirt. + +Make these changes: + +1. Extend `adopters.py` and `_data/adopters.yml` so they carry the "Use-Case" text from `ADOPTERS.md`. +2. Show the text on the website as a tooltip or an expandable card on each logo, so the wall becomes a set of short, attributed testimonials. +3. For each `ADOPTERS.md` vendor entry whose link is a corporate homepage, ask the vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, and update the link. +4. Ask the maintainers whether to drop the logo from the Vendors section when a vendor has no such page. + +Check that the tooltip or card works with keyboard navigation and on touch devices. + +## What you expected + +Each adopter logo shows a short use case, and vendor logos link to pages that mention KubeVirt. + +## URL + +- https://kubevirt.io/ (End Users and Vendors logo walls) +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/adopters.yml +- https://github.com/kubevirt/kubevirt.github.io/blob/main/ADOPTERS.md + +## Additional context + +Related: #9053 adds the adopters page that should display the same use-case data. Land #9053 first, or share the data changes between both pull requests. + +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). diff --git a/analyses/2026/kubevirt/issues/9055-add-blog-categories.md b/analyses/2026/kubevirt/issues/9055-add-blog-categories.md new file mode 100644 index 00000000..9a4be671 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9055-add-blog-categories.md @@ -0,0 +1,31 @@ +--- +title: Add blog categories and tags #9055 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +This issue affects the main website, `kubevirt/kubevirt.github.io`. Blog posts use only the `news` and `uncategorized` categories, so the blog index cannot filter posts by what readers care about, such as a release, a feature, community news, or a user story. + +Add a category or tag scheme to the website blog: + +1. Define a small, documented set of categories, for example `release`, `feature`, `community`, and `user-story`. Ask the maintainers to confirm the list. +2. Add the new category values to the front matter of the recent posts, and backfill enough of them that each category has several entries. +3. Update the blog index layout so readers can filter by category, or add one page per category. +4. Document the scheme in the website README so new posts use it. + +## What you expected + +A reader can filter the blog by release, feature, community, and user story, and new posts follow the documented scheme. + +## URL + +- https://kubevirt.io/blogs/ +- https://github.com/kubevirt/kubevirt.github.io/tree/main/_posts + +## Additional context + +The assessment did not specify the final category names, so treat the list above as a proposal for the maintainers to confirm. + +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). diff --git a/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md b/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md new file mode 100644 index 00000000..fc49fcff --- /dev/null +++ b/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md @@ -0,0 +1,32 @@ +--- +title: Enable production-only analytics and a 404 report on the user guide #9056 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The user guide has no analytics, so the project cannot see which pages readers use, which search terms they enter, or which URLs return a 404. Missing redirects therefore go unnoticed. The main website already loads an Adobe Analytics tag. + +Enable analytics on the guide in `kubevirt/user-guide`: + +1. Add the analytics snippet. Either add an `extra.analytics` block to `mkdocs.yml` (the Material theme supports Google Analytics 4), or add an `overrides/main.html` partial that loads the same Adobe Analytics tag as the website. Ask the maintainers which service to use. +2. Load the snippet only in production. Template it from the Netlify `CONTEXT` variable in the `netlify.toml` build command, so it is injected only when `CONTEXT` equals `production`. +3. Create a recurring 404 report, for example a saved report filtered on the not-found page title. +4. Use the report to add missing entries to the `redirects` map in `mkdocs.yml`, and describe the process in `README.md`. + +## What you expected + +Production page views, search terms, and 404 hits are captured, previews send no data, and the 404 report drives redirect fixes. + +## URL + +- https://kubevirt.io/user-guide/ +- `mkdocs.yml` +- `netlify.toml` + +## Additional context + +Related: #9057 gates analytics on the website, #9058 fixes the guide's preview builds in `netlify.toml`, and #9060 records who owns the analytics account. Edit `netlify.toml` in coordination with #9058. + +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). diff --git a/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md b/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md new file mode 100644 index 00000000..550f840f --- /dev/null +++ b/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md @@ -0,0 +1,32 @@ +--- +title: Fix robots.txt and gate analytics on kubevirt.io #9057 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +This issue affects the main website, `kubevirt/kubevirt.github.io`. The `robots.txt` file on kubevirt.io points to an incorrect sitemap URL and does not list the user guide sitemap. The website also loads the `dpal.js` analytics script in every build, so preview and branch deploys can pollute production data, and nothing explicitly asks search engines to skip non-production deploys. + +Make these changes in `kubevirt/kubevirt.github.io`: + +1. Correct the sitemap URL in `robots.txt` to `https://kubevirt.io/sitemap.xml`, and add a second line, `Sitemap: https://kubevirt.io/user-guide/sitemap.xml`. +2. In `_includes/head.html`, wrap the `dpal.js` include in a check on `jekyll.environment == "production"`. +3. Set `JEKYLL_ENV=production` only in the Netlify production context in `netlify.toml`. +4. Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file or a `[context.deploy-preview]` and `[context.branch-deploy]` section in `netlify.toml`. + +## What you expected + +`robots.txt` lists both sitemaps, only production builds load analytics, and deploy previews carry a `noindex` header. + +## URL + +- https://kubevirt.io/robots.txt +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_includes/head.html +- https://github.com/kubevirt/kubevirt.github.io/blob/main/netlify.toml + +## Additional context + +Related: #9056 adds analytics to the user guide, and #9058 applies the `noindex` change to the guide's `netlify.toml`. + +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). diff --git a/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md b/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md new file mode 100644 index 00000000..9817c5e0 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md @@ -0,0 +1,33 @@ +--- +title: Make guide preview builds reproducible and non-indexable #9058 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Netlify build in `netlify.toml` installs unpinned packages with `pip install mkdocs mkdocs-awesome-nav mkdocs-material mkdocs-redirects`. Preview builds can differ from the Prow image build and can break when a package releases. The build command also contains a `sed` line that rewrites `site_url: https://kubevirt.io/docs`. `mkdocs.yml` already sets `site_url` to `https://kubevirt.io/user-guide`, so the line has no effect. Nothing tells search engines to skip preview deploys. + +Update `netlify.toml` in `kubevirt/user-guide`: + +1. Remove the obsolete `sed -i 's|site_url: https://kubevirt.io/docs|...` line. +2. Pin the versions of `mkdocs`, `mkdocs-awesome-nav`, `mkdocs-material`, and `mkdocs-redirects`, or move them to a `requirements.txt` that the build installs. Match the versions in the Prow image used by `kubevirt/project-infra`. +3. Emit `X-Robots-Tag: noindex` for non-production deploys by adding a `_headers` file or `[context.deploy-preview]` and `[context.branch-deploy]` sections. + +Build a preview and confirm the header with `curl -I`. + +## What you expected + +Preview builds use the same package versions as the Prow image, the build command has no dead lines, and preview deploys return `X-Robots-Tag: noindex`. + +## URL + +- `netlify.toml` +- `mkdocs.yml` +- https://kubevirt.io/user-guide/ + +## Additional context + +Related: #9056 also edits the `netlify.toml` build command, and #9057 applies the `noindex` change to the website repository. Ask the maintainers whether the Prow image or Netlify is the source of truth for versions. + +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). diff --git a/analyses/2026/kubevirt/issues/9059-unify-search.md b/analyses/2026/kubevirt/issues/9059-unify-search.md new file mode 100644 index 00000000..2af2850a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -0,0 +1,32 @@ +--- +title: Unify search across the guide and the website #9059 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Readers cannot search the full KubeVirt documentation set from one place. The guide's search covers only the user guide, and the main website search (the lunr index in `_layouts/search.html` of `kubevirt/kubevirt.github.io`) covers only `site.posts`. The API reference and quickstarts are not searchable from either. + +Work on this in two steps: + +1. Ask the website maintainers whether the API reference and quickstarts can be indexed by the same search as the guide, for example by moving the guide search to a site-wide index. Record the answer in this issue. +2. Implement the quick improvements in `kubevirt/kubevirt.github.io`: extend the lunr index in `_layouts/search.html` to include `site.pages` in addition to `site.posts`, and add a link from the website search page to the guide search (and the other way around). + +If the maintainers choose a site-wide index, open a follow-up issue for it with the agreed scope. + +## What you expected + +A reader who starts on either site can find documentation pages from the other, and the maintainers' decision about a single search index is recorded. + +## URL + +- https://kubevirt.io/user-guide/ (search box) +- https://kubevirt.io/search/ +- https://github.com/kubevirt/kubevirt.github.io/blob/main/_layouts/search.html + +## Additional context + +Related: #9042 adds an API reference entry to the guide navigation, and #9045 asks whether the two sites should converge on one toolchain, which would simplify search. + +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). diff --git a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md new file mode 100644 index 00000000..93d32156 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -0,0 +1,35 @@ +--- +title: Document site infrastructure ownership #9060 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +No document names who administers the infrastructure behind the guide and the website. A maintainer who needs Netlify access, a DNS change, an analytics report, or a 404 report has nobody to ask. The site also cannot set a `Strict-Transport-Security` header, because GitHub Pages does not allow custom response headers. + +Add a "Site infrastructure" section to the README of both `kubevirt/user-guide` and `kubevirt/kubevirt.github.io`, or one page in `kubevirt/community` that both READMEs link to. Ask the maintainers who the custodians are, then list for each item the owner and how to request access: + +- The Netlify site. +- GitHub Pages and the custom-domain settings. +- DNS for kubevirt.io. +- The Adobe Analytics property and Google Search Console, including how to request a 404 report. +- The Prow job definitions in `kubevirt/project-infra`. + +Add an HSTS item: ask whether a DNS or CDN provider in front of kubevirt.io can set `Strict-Transport-Security`. If none exists, record the limitation as a known gap. + +## What you expected + +A maintainer can read one section and find the owner of every piece of site infrastructure, how to request access, and the known HSTS gap. + +## URL + +- https://github.com/kubevirt/user-guide/blob/main/README.md +- https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md +- https://kubevirt.io/user-guide/ + +## Additional context + +Related: #9041 adds a "Where documentation lives" section to the same READMEs, #9056 and #9057 enable and gate analytics, and #9045 records the toolchain decision. + +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). diff --git a/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md new file mode 100644 index 00000000..bdb5df68 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md @@ -0,0 +1,21 @@ +--- +title: Create a new-user getting started path #9061 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +A new user cannot go from a working cluster to a running VirtualMachine without piecing together the Installation, `virtctl`, Basic Use, and Lifecycle pages. The sub-issues below add a single Getting Started page, rewrite Basic Use around VirtualMachine, put the core installation procedure first, and make the commands on those pages easy to copy. Start with the code-copy change, then work the pages in the order a new user reads them. + +This umbrella 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). + +## Sub-issues + +- [Enable code copy and search features in mkdocs.yml #9006](9006-enable-code-copy-search.md) +- [Restructure the Installation page around the core procedure #9004](9004-restructure-installation-page.md) +- [Create an Installing virtctl page #9005](9005-create-installing-virtctl-page.md) +- [Add a Getting Started page after Architecture #9001](9001-add-getting-started-page.md) +- [Rewrite Basic Use as "Your first VirtualMachine" #9002](9002-rewrite-basic-use.md) +- [Add a Start here link and fix the Slack link on the Welcome page #9003](9003-fix-welcome-page-links.md) +- [Convert shell code blocks to fenced blocks #9007](9007-convert-shell-code-blocks.md) diff --git a/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md new file mode 100644 index 00000000..97a9bf14 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md @@ -0,0 +1,21 @@ +--- +title: Fix navigation gaps and reorganize information architecture #9062 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +Some pages are unreachable from the navigation, the Release Notes sit in the middle of the section list, section headings give no overview, and several page titles name an API instead of a reader goal. The sub-issues below fix the broken navigation first, then add landing pages, rename titles, remove legacy content, and split the longest pages. Most changes touch the same `.nav.yml` files and `mkdocs.yml` redirects, so work them in order to avoid merge conflicts. + +This umbrella 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). + +## Sub-issues + +- [Fix orphaned pages and Release Notes placement in navigation #9008](9008-fix-navigation-orphans.md) +- [Add an API reference entry to the guide navigation #9042](9042-add-api-reference-link.md) +- [Remove or archive legacy installation content #9011](9011-remove-legacy-installation-content.md) +- [Add landing pages to Compute, Network, and Storage #9009](9009-add-section-landing-pages.md) +- [Rename API-centric titles and group legacy workload pages #9010](9010-rename-api-page-titles.md) +- [Split the Disks and Volumes and Interfaces and Networks pages #9050](9050-split-disks-networks-pages.md) +- [Split the Live Migration and Release Notes pages #9051](9051-split-migration-release-notes.md) diff --git a/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md new file mode 100644 index 00000000..e2a1fc52 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md @@ -0,0 +1,19 @@ +--- +title: Fill feature and reference coverage gaps #9063 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +Several v1.9 features appear only in the release notes, the guide has no `virtctl` command reference or feature-gate table, and users have no troubleshooting page. The sub-issues below add the missing feature documentation and the reference and troubleshooting pages readers look for first. The `virtctl` reference and feature-gate table can link to the feature pages, so write those pages first. + +This umbrella 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). + +## Sub-issues + +- [Document the VirtualMachineBackup API #9012](9012-document-virtualmachinebackup-api.md) +- [Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression #9013](9013-document-v19-features.md) +- [Create a virtctl command reference #9014](9014-create-virtctl-reference.md) +- [Add a feature-gate table #9015](9015-add-feature-gate-table.md) +- [Add a user-facing Troubleshooting page #9016](9016-add-troubleshooting-page.md) diff --git a/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md new file mode 100644 index 00000000..b8f22bac --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md @@ -0,0 +1,17 @@ +--- +title: Publish versioned docs and standardize feature states #9064 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +Readers cannot tell which KubeVirt version a page describes, and contributors cannot tell how release branches and cherry-picks work. The sub-issues below standardize the feature-state admonition, document the versioning model, and publish versioned documentation with a version selector. Work them in order: the feature-state format helps immediately, the documented model must be confirmed by maintainers before publishing, and the version selector builds on that model. + +This umbrella 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). + +## Sub-issues + +- [Standardize the feature-state admonition #9017](9017-standardize-feature-state-admonition.md) +- [Document the content versioning model, release-notes process, and localization #9018](9018-document-versioning-model.md) +- [Publish versioned documentation with a version selector #9019](9019-publish-versioned-docs.md) diff --git a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md new file mode 100644 index 00000000..ade898a4 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md @@ -0,0 +1,20 @@ +--- +title: Build a documentation contributor guide #9065 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +`CONTRIBUTING.md` is a pointer, and the repository has no pull request template, style guide, per-area reviewers, or stale-PR policy. The sub-issues below give contributors the guidance and tooling they need to propose, write, and review a documentation change. Start with the pull request template and style guide, which are quick wins, then expand the contributor guide that links to them. + +This umbrella 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). + +## Sub-issues + +- [Add a pull request template #9022](9022-add-pull-request-template.md) +- [Add a documentation style guide #9021](9021-add-style-guide.md) +- [Expand CONTRIBUTING.md into a documentation contributor guide #9020](9020-expand-contributing-guide.md) +- [Add per-directory OWNERS files #9023](9023-add-owners-files.md) +- [Add MAINTAINERS.md and a maintainer ladder #9026](9026-add-maintainers-file.md) +- [Triage open pull requests and add a stale-PR policy #9025](9025-triage-open-prs.md) diff --git a/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md new file mode 100644 index 00000000..30a8bb57 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md @@ -0,0 +1,20 @@ +--- +title: Improve the Contributing page for new contributors #9066 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +A newcomer who opens the Contributing page finds a list of links but no explanation of how the project is run, where to ask for help, which issues to pick up, or what the first change looks like. The sub-issues below add that context to the page and fix the beginner issue labels and backlog it points to. Standardize the label first so the issue links on the page stay valid. + +This umbrella 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). + +## Sub-issues + +- [Standardize the good first issue label #9038](9038-standardize-good-first-issue.md) +- [Add a project overview and resource descriptions to the Contributing page #9034](9034-add-contributing-overview.md) +- [Link filtered issue lists and explain labels on the Contributing page #9036](9036-link-issue-lists.md) +- [Add where-to-ask-help and the VEP docs deadline to the Contributing page #9035](9035-add-help-and-vep-guidance.md) +- [Add a first documentation change walkthrough to the Contributing page #9037](9037-add-first-change-walkthrough.md) +- [Triage the issue backlog and publish a triage cadence #9039](9039-triage-issue-backlog.md) diff --git a/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md new file mode 100644 index 00000000..63054e4f --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md @@ -0,0 +1,19 @@ +--- +title: Document community channels and governance #9067 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +Readers who stay in the user guide cannot find the project's Slack channels, mailing list, meetings, governance documents, or a home for documentation work. The sub-issues below put repository and social links on every page, add a Community and communication page, link the community from the guide, explain how the project is governed, and give documentation a SIG home. Add the footer links first because they are a one-file change. + +This umbrella 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). + +## Sub-issues + +- [Add repository and social links to the footer #9032](9032-add-footer-social-links.md) +- [Add a Community and communication page to the guide #9030](9030-add-community-page.md) +- [Add a Community and adoption block to the index and Contributing page #9031](9031-add-community-adoption-links.md) +- [Add a Governance section to the kubevirt.io Community page #9040](9040-add-governance-section.md) +- [Give documentation a SIG home and clarify SIG meeting mechanics #9024](9024-give-docs-sig-home.md) diff --git a/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md new file mode 100644 index 00000000..fc2a91ba --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md @@ -0,0 +1,17 @@ +--- +title: Apply inclusive language and legacy naming updates #9068 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +The guide links to a legacy `master` branch path, uses `master` as an example node name, and relies on minimizing words such as "simply" and "easily". The sub-issues below fix the legacy references, reword the prose, and add an automated check so new occurrences are caught in pull requests. Fix the legacy references first because they are small and exact. + +This umbrella 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). + +## Sub-issues + +- [Fix legacy master links and the node-name example #9029](9029-fix-legacy-master-references.md) +- [Reword minimizing language and cancel terminology #9027](9027-reword-minimizing-language.md) +- [Add accessibility and language checks to CI #9028](9028-add-ci-doc-checks.md) diff --git a/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md new file mode 100644 index 00000000..c89fbd63 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md @@ -0,0 +1,18 @@ +--- +title: Apply accessibility and branding improvements #9069 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +The guide's header and link colors have low contrast, the logo has no useful alt text, wide tables and the Architecture diagram do not work well on mobile or with screen readers, and the guide's brand colors differ from the main site. The sub-issues below fix these problems and record the brand values so both sites stay aligned. Fix the logo and unused assets first, then the contrast and mobile issues, then publish the brand reference. + +This umbrella 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). + +## Sub-issues + +- [Fix logo alt text and remove unused assets and config #9033](9033-fix-logo-and-unused-assets.md) +- [Fix mobile tables and replace the Architecture diagram #9049](9049-fix-mobile-tables.md) +- [Fix header and link contrast and align brand colors #9048](9048-fix-contrast-and-colors.md) +- [Publish a brand reference #9052](9052-publish-brand-reference.md) diff --git a/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md new file mode 100644 index 00000000..54fdbf77 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md @@ -0,0 +1,19 @@ +--- +title: Fix website compliance and adopter content #9070 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +The user guide and kubevirt.io footers do not meet the CNCF project website requirements, the website lacks community health files, and the site shows adopter logos without case studies or use cases. The sub-issues below fix the footers and health files, then add the adopters page, adopter use cases, and blog categories. Fix the footers first because they are compliance items. + +This umbrella 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). + +## Sub-issues + +- [Fix the website footer and add community health files #9047](9047-fix-website-footer.md) +- [Bring the user guide footer into compliance #9046](9046-fix-guide-footer.md) +- [Add an adopters page and link CNCF case studies #9053](9053-add-adopters-page.md) +- [Show adopter use cases and KubeVirt-specific vendor links #9054](9054-show-adopter-use-cases.md) +- [Add blog categories and tags #9055](9055-add-blog-categories.md) diff --git a/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md new file mode 100644 index 00000000..12326559 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md @@ -0,0 +1,18 @@ +--- +title: Enable analytics and fix SEO configuration #9071 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +The user guide collects no analytics, preview deploys can be indexed and pollute analytics on the main site, `robots.txt` points at the wrong sitemap, and search covers only part of the documentation. The sub-issues below fix the indexing and build configuration first, then enable production-only analytics, and finally unify search. Work the configuration fixes first so analytics data is clean from the start. + +This umbrella 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). + +## Sub-issues + +- [Make guide preview builds reproducible and non-indexable #9058](9058-fix-guide-preview-builds.md) +- [Fix robots.txt and gate analytics on kubevirt.io #9057](9057-fix-robots-and-site-analytics.md) +- [Enable production-only analytics and a 404 report on the user guide #9056](9056-enable-guide-analytics.md) +- [Unify search across the guide and the website #9059](9059-unify-search.md) diff --git a/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md new file mode 100644 index 00000000..5975b0b6 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md @@ -0,0 +1,19 @@ +--- +title: Document site ownership and content boundaries #9072 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Umbrella Issue + +Documentation is spread across the user guide, kubevirt.io, `kubevirt/kubevirt/docs`, and the CDI repository without a stated boundary, and no one document records who administers the site infrastructure. The sub-issues below document where documentation lives and who owns the infrastructure, decide whether the website and guide should converge, and audit the other repositories for user-facing content. Record the boundary and ownership first; the audits and the toolchain decision depend on them. + +This umbrella 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). + +## Sub-issues + +- [Document where documentation lives #9041](9041-document-content-boundary.md) +- [Document site infrastructure ownership #9060](9060-document-site-infrastructure.md) +- [Decide whether to converge the website and user guide #9045](9045-decide-converge-toolchains.md) +- [Audit kubevirt/kubevirt docs for user-facing content #9043](9043-audit-kubevirt-docs.md) +- [Audit CDI documentation for storage pages #9044](9044-audit-cdi-docs.md) diff --git a/analyses/2026/kubevirt/issues/U-accessibility-improvements.md b/analyses/2026/kubevirt/issues/U-accessibility-improvements.md deleted file mode 100644 index 5e44d036..00000000 --- a/analyses/2026/kubevirt/issues/U-accessibility-improvements.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Improve accessibility, mobile usability, and code block formatting -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -The guide's brand teal header and link color fall below the 4.5:1 contrast ratio -that WCAG AA requires, the Architecture page's stack diagram is ASCII art that -screen readers cannot interpret, wide tables may overflow on phones, and most -code blocks use `$`-prefixed indented formatting that pastes badly and scrolls -horizontally. Several pages exceed 500 lines, which makes them hard to navigate -on any device. - -The sub-issues below fix the contrast and diagram problems, modernize the code -blocks starting with the new-user path, split the longest pages, and add an -automated check so the fixes stay fixed. Enable `content.code.copy` first -(tracked in the configuration quick-wins issue) so the code block work shows its -full benefit. - -## Sub-issues - -### Fix header and link contrast and align the brand color with the main site - -In `docs/stylesheets/extra.css`: - -- Darken `--md-primary-fg-color` to a teal that gives at least 4.5:1 against - white, or keep the brand teal for decorative elements only and set the header - and tab text to a dark foreground. -- Replace the `filter: brightness(80%)` link rule with explicit - `--md-typeset-a-color` values per color scheme, each checked against 4.5:1. -- Replace the ad hoc `#0db2b6` primary with a value from the main site's - documented `$kv-color--green-*` scale, for example `#00aab2`, or ask the - website maintainers to add `#0db2b6` to the scale so both properties draw from - one list. - -Verify both light and dark schemes with a contrast checker. - -Done when: header text and links meet 4.5:1 in both schemes and the primary -color matches the main site's scale. - -### Replace the ASCII architecture diagram with an accessible diagram - -On the Architecture page (`docs/architecture.md`), replace the ASCII stack -diagram with a Mermaid diagram (enable `pymdownx.superfences` custom fences for -`mermaid` in `mkdocs.yml`) or an image with descriptive alt text. Add a -one-paragraph prose description of the layers so screen reader and mobile users -get the same information. - -Done when: the diagram renders on mobile and its content is available as text. - -### Verify wide tables on mobile and add table captions - -On a phone, check that the tables on -`docs/cluster_admin/feature_gate_status_on_Arm64.md` and -`docs/cluster_admin/device_status_on_Arm64.md` scroll horizontally rather than -overflowing the page. If they overflow, remove the -`display: table; width: max-content` override from `extra.css` or scope it to -specific tables with `attr_list` classes. Add a short caption or introductory -sentence above each wide status table stating what it shows. - -Done when: no table overflows on a 375 px viewport and each status table has a -caption. - -### Convert code blocks on the new-user path to fenced blocks - -On Installation, Installing virtctl, Basic Use, and Lifecycle, convert -`$`-prefixed indented code blocks to fenced `shell` blocks without prompt -characters. Place example output in a separate block or a `title="Output"` -annotation so commands paste cleanly. Break commands over 100 characters across -lines with `\` continuations. - -Done when: every command on these pages can be copied and pasted without -editing. - -### Convert code blocks on the longest reference pages - -Apply the same conversion to Disks and Volumes -(`docs/storage/disks_and_volumes.md`), Export API -(`docs/storage/export_api.md`), Interfaces and Networks -(`docs/network/interfaces_and_networks.md`), and Live Migration -(`docs/compute/live_migration.md`). - -Done when: these four pages contain no `$`-prefixed indented code blocks. - -### Split Disks and Volumes by volume type - -Split `docs/storage/disks_and_volumes.md` into an overview page plus one page -per volume type or group of related types. Add the new pages to -`docs/storage/.nav.yml` and redirects for any anchors that external pages link -to. - -Done when: no resulting page exceeds about 500 lines and existing links resolve. - -### Split Interfaces and Networks and Live Migration - -- Split `docs/network/interfaces_and_networks.md` so binding methods and network - attachment are separate pages. -- Move the migration strategies and network configuration sections of - `docs/compute/live_migration.md` to sub-pages. - -Update the `.nav.yml` files and add redirects. - -Done when: each resulting page is under about 500 lines and existing links -resolve. - -### Split Release Notes by minor release - -Split `docs/release_notes.md` into one page per minor release, or paginate it, -and set the Release Notes navigation entry to open the newest release. Update -`update_changelog.sh` so regeneration writes to the new structure. - -Done when: the newest release opens first and older releases load on separate -pages. - -### Add an accessibility check to CI - -Add an accessibility check to the Makefile and the Prow pre-submit, for example -`pa11y-ci` or Lighthouse run against the built site for a sample of pages, so -contrast regressions are caught in pull requests. - -Done when: a pull request that lowers contrast below 4.5:1 fails the check. diff --git a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-build-contributor-guide.md deleted file mode 100644 index 7fe2be68..00000000 --- a/analyses/2026/kubevirt/issues/U-build-contributor-guide.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Build a documentation contributor guide and review process -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -`CONTRIBUTING.md` is a pointer, the Contributing page lists links without -explaining them, and there is no style guide, pull request template, or named -documentation maintainer. New contributors cannot tell how to make a change, who -reviews it, or what "done" looks like, and twelve pull requests sit open. - -The sub-issues below turn `CONTRIBUTING.md` and `docs/contributing.md` into a -complete contributor guide, add the supporting files that make reviews -predictable, and route reviews to the right people. The Thanos "How to -contribute to docs" page and the NATS `MAINTAINERS` file are good models. - -## Sub-issues - -### Expand CONTRIBUTING.md into a full documentation contributor guide - -Rewrite `CONTRIBUTING.md` to cover the full lifecycle: how to propose a change, -how to build and test locally (move the build steps from the README here), what -happens after opening a pull request (labels, `/lgtm`, `/approve`, expected -turnaround), when to add a redirect to `mkdocs.yml`, and when a change needs a -cherry-pick to a `release-vX.Y-stable` branch. Summarize the key points on the -Contributing page and link to the full guide. - -Done when: a first-time contributor can go from clone to merged PR using only -this file. - -### Add a "Making your first documentation change" walkthrough - -Add a section to `docs/contributing.md` that walks through the mechanics end to -end: find or file an issue, comment to claim it, fork and branch, edit under -`docs/` and update `.nav.yml`, run `make check_spelling` and `make check_links`, -sign off with `git commit -s`, open the pull request, and what to expect from -Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. - -Done when: every step names the command or UI action to take. - -### Add "Where to ask for help" and direct links to beginner issues - -On `docs/contributing.md`, and repeated in `CONTRIBUTING.md`: - -- Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and - `#virtualization` for usage questions, and link the Slack invitation page. -- State that the weekly community meeting includes newcomer introductions, with - the day, time, and meeting link. -- Identify the documentation approvers or a docs contact. -- Replace the generic "look for good-first-issue" advice with direct links to - the filtered issue list for each repository. -- Link the `kubevirt/community` resources newcomers need: the SIG list, the - help-wanted guide, the community meeting document, and the `MAINTAINERS` file. - -Done when: a newcomer can find a person to ask and an issue to pick up from this -page. - -### Explain how the project is run on the Contributing page - -Above the "Important community resources" list on `docs/contributing.md`, add a -short "How the project is run" paragraph that names the maintainer group, -explains that work is organized in SIGs, and states that decisions default to -lazy consensus. Give each link in the resource list a one-sentence description -of what the reader will find. - -Done when: a newcomer understands the structure before following any link. - -### Add a "Contributing to the code" subsection and document mentoring - -Add a subsection to `docs/contributing.md` that summarizes the -`kubevirt/kubevirt` path in three or four steps: read its `CONTRIBUTING.md`, -follow `docs/getting-started.md` to build and run a local cluster, pick an -issue, open a draft PR. - -Ask the community whether a mentoring or buddy arrangement exists for first-time -contributors. The help-wanted guide promises "extra assistance" on -`good first issue` items; state how to request it. - -Done when: code-minded newcomers see a clear next step and know how to ask for -help. - -### Write a documentation style guide - -Add a short style guide, linked from `CONTRIBUTING.md` and the Contributing -page, that covers: - -- Page structure: title, short concept, feature-state banner, procedure, related - links. -- The standard feature-state admonition. -- Code block conventions: fenced blocks, no `$` prompts, output in a separate - block. -- Kubernetes object capitalization (VirtualMachine, VirtualMachineInstance) and - file naming. -- A rule that discourages "simple", "simply", "easy", "easily", "just", and - "obviously", with a one-line explanation of why. - -Done when: a reviewer can point to the guide for each common review comment. - -### Add a pull request template - -Add `.github/PULL_REQUEST_TEMPLATE.md` with a checklist: `.nav.yml` updated for -new pages, redirect added for moved pages, spelling and link checks run, -feature-state banner present, and the related `kubevirt/kubevirt` PR or VEP -linked. - -Done when: new pull requests open with the checklist. - -### Code-freeze requirement, stale-PR policy, triage open pull requests - -- On the Contributing page, state that the VEP checklist requires the docs PR to - be merged by code freeze. -- Add a stale-PR policy to `CONTRIBUTING.md` so contributors know what to - expect. -- Triage the currently open pull requests: merge or close the oldest, and leave - a comment on each remaining one stating what it needs. - -Done when: the policy is published and every open PR has a current status -comment. - -### Name maintainers and route reviews to subject-matter experts - -- Add a `MAINTAINERS.md`, or a "Maintainers" section on the Contributing page, - that names the user guide approvers and the person or group responsible for - the release-notes script, and how to reach them. -- Add per-directory `OWNERS` files (`docs/network/OWNERS`, - `docs/storage/OWNERS`, `docs/compute/OWNERS`) that reference the existing - `sig-network-*`, `sig-storage-*`, and `sig-compute-*` aliases, keeping the - root approvers for site-wide changes. -- Ask the maintainers to consider a documentation-focused reviewer role or SIG - Docs alias so writers who are not code approvers can share the review load. - -Done when: a pull request touching `docs/storage/` requests review from the -storage alias. diff --git a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-create-getting-started-path.md deleted file mode 100644 index 46aa24d3..00000000 --- a/analyses/2026/kubevirt/issues/U-create-getting-started-path.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: - Create a new-user Getting Started path from installation to a running - VirtualMachine -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -A new user who arrives at the user guide cannot follow one path from "I have a -cluster" to "I have a running VM." The Installation page buries the four-command -install under platform-specific material, the `virtctl` page covers only one -binary, Basic Use centers on VirtualMachineInstance rather than VirtualMachine, -Lifecycle references a `vmi.yaml` that is never defined, and nothing on the -Welcome page tells a newcomer where to start. - -The sub-issues below add a single Getting Started page and reshape the pages it -links to so each one hands the reader to the next. Complete the sub-issues in -order where possible; the later ones link to pages created by the earlier ones. - -## Sub-issues - -### Add a Getting Started page after Architecture - -Create `docs/getting_started.md` and add it to `docs/.nav.yml` immediately after -Architecture. On one page, walk a reader from a working cluster to a running VM: - -1. Install KubeVirt with the four `kubectl` commands from the Installation page. -2. Install `virtctl`. -3. Create a VirtualMachine from a provided minimal manifest or - `virtctl create vm`. -4. Start it, connect with `virtctl console`, and stop it. - -Link to the detailed page at each step rather than repeating its content. -Consider folding the current Quickstarts page into this page as a "Try it in a -sandbox" section. - -Done when: a reader can complete the page in under 30 minutes on a fresh cluster -and every step links to the page that explains it. - -### Point newcomers at the Getting Started page from Welcome and Quickstarts - -On the Welcome page (`docs/index.md`), add a one-line "New to KubeVirt? Start -here" link at the top that points to the Getting Started page. - -On the Quickstarts page (`docs/quickstarts.md`), add 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 -will have at the end. Add a closing link to the Getting Started page. - -Done when: both pages link to Getting Started and the Quickstarts page states -its prerequisites. - -### Rewrite Basic Use as and fix the Lifecycle manifest reference - -Rewrite `docs/user_workloads/basic_use.md` into a short page that presents -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. -- The `kubectl apply`, `virtctl start`, `virtctl console`, and `virtctl stop` - commands. -- Explicit links to the next pages (Creating VirtualMachines, Accessing Virtual - Machines, Lifecycle). - -Update `docs/user_workloads/lifecycle.md` to reference that `vm.yaml` manifest -instead of the undefined `vmi.yaml`. - -Done when: Basic Use and Lifecycle use the same manifest and a reader can run -both pages end to end. - -### Restructure the Installation page so the core procedure comes first - -Reorder `docs/cluster_admin/installation.md` so the first screen covers -Requirements, the four-command operator install, verification, and the emulation -fallback. Move the following below a "Platform-specific and advanced -installation" heading, or onto separate pages: AppArmor, kernel and user-land -compatibility, SELinux, OKD, k3OS, daily developer builds, deploying from -source, network plugins, and node placement. - -Remove, or move to a footnote, the historical notes about behavior before -v0.20.0 and v0.34.2. Ask the maintainers whether any supported upgrade path -still requires them. - -Done when: the standard install is complete before the first platform-specific -heading. - -### End the Installation page with a Next steps section - -Add a "Next steps" section to the end of `docs/cluster_admin/installation.md` -that links to Installing virtctl, Creating VirtualMachines by using virtctl, and -Accessing Virtual Machines. - -Done when: the Installation page no longer ends on an advanced topic. - -### Expand the virtctl page and rename it "Installing virtctl" - -Expand `docs/user_workloads/virtctl_client_tool.md` to cover every published -client binary. Use the Material theme's content tabs for Linux, macOS, and -Windows on both amd64 and arm64, and include the `chmod +x` and `PATH` steps. -Rename the page title to "Installing virtctl". Either move the page next to -Installation in the navigation or link to it from Installation's Next steps. - -Done when: a user on any supported platform can install `virtctl` from this page -alone. - -## Related - -The virtctl command reference and the Troubleshooting page are tracked -separately; link to them from Getting Started when they exist. diff --git a/analyses/2026/kubevirt/issues/U-document-community-channels.md b/analyses/2026/kubevirt/issues/U-document-community-channels.md deleted file mode 100644 index a018427c..00000000 --- a/analyses/2026/kubevirt/issues/U-document-community-channels.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: - Document community channels in the guide and maintain a beginner-friendly - issue backlog -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -Readers who stay inside the user guide see only a raw Slack URL on the Welcome -page; the channels, mailing list, and community meetings are documented on -`kubevirt.io/community` but not in the guide. On the contributor side, the -repository uses two spellings of the good-first-issue label, so beginner issues -do not appear in GitHub's "Contribute" tab, and unlabeled issues reach -`lifecycle/rotten` and close without triage. - -The sub-issues below bring the community information into the guide and set up -the labels, triage habits, and cadence that keep a small pool of beginner issues -available. Documentation also needs a formal home in the community SIG list so -newcomers know where to volunteer. - -## Sub-issues - -### Add a Community and communication page to the guide - -Add a page, or a section on the Contributing page, that consolidates the Slack -channels, the `kubevirt-dev` mailing list, community meetings, and social -accounts in one place. Give each channel a one-line description of its purpose: -`#virtualization` for usage questions, `#kubevirt-dev` for contributor -discussion, the mailing list for announcements and longer threads. State the -meeting cadence and times and include the public calendar link -(`kubevirt@cncf.io`). Keep the content consistent with `kubevirt.io/community`. - -On the Welcome page, replace the raw Slack URL with the channel name and a link -to the Kubernetes Slack invitation page. Add a short "Community and adoption" -block to `docs/index.md` that links to the `kubevirt.io` blog, videos, Summit, -adopters page, and Slack. On `docs/contributing.md`, where readers are invited -to submit case studies, link the existing adopters list and CNCF case studies so -contributors can see the format they are being asked to follow. - -Done when: a reader can find every channel and the meeting schedule without -leaving the guide. - -### Standardize on the `good first issue` label - -Standardize on the GitHub-native `good first issue` label (spaced) and retire or -alias the hyphenated `good-first-issue`, so beginner issues appear in GitHub's -"Contribute" tab and discovery tooling. Relabel existing issues and update the -reference on the Contributing page to match. Reference both `good first issue` -and `help wanted` on the Contributing page and explain the difference: -`help wanted` marks slightly larger but still approachable tasks. - -Done when: only one spelling of the label is in use and the Contributing page -explains both labels. - -### Triage the open issue backlog - -Apply `kind/*` and `sig/documentation` labels to unlabeled open issues, and -apply `triage/accepted` to issues that are ready to be worked on. Apply -`lifecycle/frozen` to still-relevant enhancements and documentation requests so -they do not reach `lifecycle/rotten` and close for inactivity alone. - -Done when: every open issue has a `kind/*` label and a triage state. - -### Seed and maintain a pool of beginner issues - -Identify documentation gaps, typos, and small feature-doc updates and file them -as `good first issue`, aiming for five to ten open at any time. Add a short -"good first issue" checklist to the issue templates (affected page, expected -outcome, pointers to relevant docs) so each beginner issue is self-contained. - -Done when: at least five `good first issue` items are open and each follows the -checklist. - -### Publish a documentation triage cadence and give documentation a SIG home - -Publish a lightweight triage cadence, for example a periodic documentation-issue -triage during a SIG or community meeting, so labeling, acceptance, and staleness -decisions stay consistent. Populate the `sig/documentation` entry in the -community `sig-list.md` with chairs, a meeting cadence or async channel, and a -charter that covers both the user guide and the website. - -Done when: the cadence is written down on the Contributing page and -`sig-list.md` has a complete documentation entry. diff --git a/analyses/2026/kubevirt/issues/U-document-site-ownership.md b/analyses/2026/kubevirt/issues/U-document-site-ownership.md deleted file mode 100644 index 0a1ee3a0..00000000 --- a/analyses/2026/kubevirt/issues/U-document-site-ownership.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: - Document site infrastructure ownership and the boundary between documentation - sources -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -Nobody can tell from the repositories who administers the Netlify site, DNS, -GitHub Pages, analytics, or the Prow jobs, or how to become a user guide -approver. User-facing content is also spread across three places: this guide, -`kubevirt/kubevirt/docs`, and the CDI `doc/` directory, with no statement of -which content belongs where. - -The sub-issues below write down infrastructure ownership and the maintainer -ladder so the sites survive maintainer turnover, and define and enforce a -content boundary so users find documentation in one place. - -## Sub-issues - -### Add a Site infrastructure section to the README - -Add a "Site infrastructure" section to the README of `kubevirt/user-guide` (and -propose the same for `kubevirt/kubevirt.github.io`, or a page in -`kubevirt/community`) that lists who administers the Netlify site, GitHub Pages -and custom-domain settings, DNS for `kubevirt.io`, the analytics and Search -Console accounts, and the Prow job definitions in `kubevirt/project-infra`, and -how a maintainer requests access or a 404 report. - -Done when: every piece of infrastructure names an owner and an access path. - -### Publish a maintainer ladder and keep OWNERS_ALIASES current - -In the README, describe how a contributor becomes a reviewer and then an -approver (for example, a number of merged docs PRs and a nomination), mirroring -the process in `kubevirt/community` for code SIGs. Review `OWNERS_ALIASES` and -add dated emeritus entries for inactive approvers, as the website repository -already does. - -Done when: the ladder is published and `OWNERS_ALIASES` lists only active -approvers plus dated emeritus entries. - -### Add a Strict-Transport-Security header or record the gap - -GitHub Pages does not let you set response headers directly. Either enable HSTS -through the DNS or CDN provider in front of `kubevirt.io`, or record the -limitation in the Site infrastructure section so it is a known gap. For the user -guide on Netlify, add the header in `netlify.toml`. - -Done when: `curl -I https://kubevirt.io/user-guide/` returns -`Strict-Transport-Security`, and the main site's status is recorded. - -### Document where documentation lives - -Add a short "Where documentation lives" section to the README of -`kubevirt/user-guide`, and propose the same text for -`kubevirt/kubevirt.github.io` and `kubevirt/kubevirt`, stating that user and -operator documentation belongs in the user guide, marketing, blog, and community -content belongs on the website, and `kubevirt/kubevirt/docs` is for design and -developer notes only. Link to it from `docs/contributing.md`. - -Done when: all three repositories state the same boundary. - -### Record the repository and toolchain decisions - -Decide whether the website and user guide should share a repository, and record -the decision in both READMEs with the reason (for example, different generators, -maintainers, and audiences). Open a tracking issue to evaluate converging the -two toolchains on Material for MkDocs or another generator with a supported -theme, so a single skill set covers both sites, even if the migration is -deferred. - -Done when: both decisions are written down with an owner and a revisit date. - -### Move user-facing content out of kubevirt/kubevirt/docs - -Audit `kubevirt/kubevirt/docs` for user-facing content, starting with the files -the user guide already links to (`getting-started.md`, `architecture.md`, -`cloud-init.md`). Move the user-facing portions into the guide and replace the -originals with a one-line pointer so search results and old links still resolve. - -Done when: the guide no longer links to `kubevirt/kubevirt/docs` for user-facing -content. - -### Triage the CDI documentation the guide links to - -Six storage pages link to the CDI `doc/` directory. Either move those pages into -the guide's `storage/` section, or add a "CDI reference documentation" page in -the guide that explains why the rest remains in the CDI repository and links to -it. - -Done when: every CDI link from the guide goes through a page that explains the -boundary. diff --git a/analyses/2026/kubevirt/issues/U-document-v19-features.md b/analyses/2026/kubevirt/issues/U-document-v19-features.md deleted file mode 100644 index 9fb4e176..00000000 --- a/analyses/2026/kubevirt/issues/U-document-v19-features.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Document v1.9 features and add feature-gate and virtctl reference pages -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -Several features shipped in KubeVirt v1.9 appear only in the release notes, so -users cannot find how to use them. The guide also lacks two reference pages that -readers expect: a list of feature gates with their stage and version, and a list -of `virtctl` subcommands. Feature pages that do state a stage use an informal -`FEATURE STATE:` block whose format varies. - -The sub-issues below add the missing feature documentation, create the two -reference pages, and standardize the feature-state banner so future pages follow -one pattern. - -## Sub-issues - -### Document the VirtualMachineBackup API - -Add a page under `docs/storage/` that explains the `VirtualMachineBackup` API -introduced in v1.9: what it backs up, the required feature gate, a minimal -manifest, how to check status, and how it relates to the snapshot and export -features. Add it to `docs/storage/.nav.yml` and link it from the release notes -entry. - -Done when: a user can create and verify a backup by following the page. - -### Document the CrossArchitectureVirtualization feature gate - -Add a section or page, under `docs/compute/` or `docs/cluster_admin/`, for the -`CrossArchitectureVirtualization` feature gate: what it enables, the supported -architecture combinations, how to enable it, and known limitations. Link it from -the Arm64 pages where relevant. - -Done when: the gate is documented somewhere other than the release notes. - -### Document masquerade PortRanges and MigrationPolicy compression - -- In Interfaces and Networks (`docs/network/interfaces_and_networks.md`), add a - subsection on masquerade `PortRanges` with a manifest example. -- In Migration Policies (`docs/cluster_admin/migration_policies.md`), add a - subsection on MigrationPolicy compression with a manifest example and guidance - on when to enable it. - -Done when: both features are documented on the page where users configure them. - -### Create a virtctl command reference - -Create a `virtctl` command reference page, or expand -`docs/user_workloads/virtctl_client_tool.md` beyond installation, that lists -each subcommand with a one-line description and a link to the feature page that -explains it in context. Generate the subcommand list from `virtctl --help` for -the current release so it is complete. - -Done when: every `virtctl` subcommand appears with a description and a link. - -### Add a feature-gate table to the feature gates page - -On Activating and Deactivating Feature Gates -(`docs/cluster_admin/activating_feature_gates.md`), add a table that lists each -feature gate, its stage (Alpha, Beta, GA, Deprecated), the version it was -introduced or graduated, and a link to its documentation. Ask the maintainers -whether this table can be generated from the `kubevirt/kubevirt` source to avoid -drift; if so, document the generation step. - -Done when: every feature gate in the current release appears in the table. - -### Standardize the feature-state admonition and apply it to every feature page - -Define a standard feature-state admonition that states the version introduced -and the current stage (Alpha, Beta, GA, Deprecated). Document its format in -`CONTRIBUTING.md`. Replace the existing `FEATURE STATE:` blocks on the pages -that have them and add the admonition to feature pages that have none. - -Done when: every feature page opens with the same admonition format. diff --git a/analyses/2026/kubevirt/issues/U-enable-analytics.md b/analyses/2026/kubevirt/issues/U-enable-analytics.md deleted file mode 100644 index a5365a95..00000000 --- a/analyses/2026/kubevirt/issues/U-enable-analytics.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Enable analytics on the user guide and use it to fix broken links -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -The user guide collects no analytics, so maintainers cannot see which pages are -read, what users search for, or which URLs return 404. The main site has an -Adobe Analytics tag, but it also fires on preview deploys, which pollutes the -data. The sub-issues below add analytics to the guide, restrict it to -production, and set up the one report that pays for itself: a list of 404 hits -to feed the `redirects` map in `mkdocs.yml`. - -## Sub-issues - -### Enable analytics on the user guide - -Add an `extra.analytics` block to `mkdocs.yml`. The Material theme supports -Google Analytics 4 natively; alternatively, add a custom `overrides/main.html` -partial that loads the same Adobe Analytics tag the main site uses so both -properties report to one place. Confirm with the website maintainers which -property to use. - -Done when: page views from `kubevirt.io/user-guide` appear in the chosen -analytics property. - -### Load analytics only in production - -Inject the analytics snippet only when the Netlify `CONTEXT` variable equals -`production`, for example by templating it in the `netlify.toml` build command -or by reading an environment variable in the override partial. - -Done when: a deploy preview loads no analytics script. - -### Set up a recurring 404 report and feed it into the redirects map - -Once analytics are live, create a saved report filtered on the not-found page -title, review it on a regular cadence, and add missing entries to the -`redirects` plugin map in `mkdocs.yml`. Document the cadence and the report -location in the README's site infrastructure section. - -Done when: the report exists and the first batch of redirects from it is merged. diff --git a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md b/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md deleted file mode 100644 index 0eea2aeb..00000000 --- a/analyses/2026/kubevirt/issues/U-fix-kubevirt-io-gaps.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Fix kubevirt.io compliance, SEO, and adopter content gaps -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -The documentation analysis covered the main `kubevirt.io` website as well as the -user guide, and found gaps on the website that affect documentation users: the -copyright line is missing its © symbol, `robots.txt` points at the wrong sitemap -and omits the user guide's, the site search indexes only blog posts, there is no -root `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md`, two published CNCF case studies -are not linked anywhere, and the adopter use cases in `ADOPTERS.md` never reach -the site. - -All changes in this issue land in the `kubevirt/kubevirt.github.io` repository. -The issue is filed here so the documentation work is tracked in one place; -transfer it if the maintainers prefer. - -## Sub-issues - -### Add the © symbol and the missing root repository files - -- In `_includes/footer.html`, change the copyright line to read "Copyright © - KubeVirt a Series of LF Projects, LLC". -- Add a root `CONTRIBUTING.md` that points to the existing contributing content - in the README and to the user guide's Contributing page. -- Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code of - conduct. -- Add a note to the README naming the file to edit when the CNCF maturity - statement changes. - -Done when: the footer shows ©, and both files exist at the repository root. - -### Fix robots.txt, gate analytics to production, and block indexing of previews - -- In `robots.txt`, correct the sitemap URL to `https://kubevirt.io/sitemap.xml` - and add a second `Sitemap:` line for - `https://kubevirt.io/user-guide/sitemap.xml`. -- In `_includes/head.html`, wrap the `dpal.js` Adobe Analytics include in a - check on `jekyll.environment == "production"`, and set `JEKYLL_ENV=production` - only in the Netlify production context. -- Emit `X-Robots-Tag: noindex` for deploy previews and branch deploys from a - `_headers` file or `netlify.toml` context section. - -Done when: `robots.txt` lists both sitemaps, previews send no analytics, and -previews return the `noindex` header. - -### Link the existing CNCF case studies from the landing page - -Add a "Case Studies" block beneath the End Users logo wall on the landing page -that links the two published CNCF case studies (NTT Docomo Business and -Swisscom). The content already exists; this is a quick win. - -Done when: both case studies are reachable from the landing page. - -### Show adopter use cases on the logo wall - -Extend `adopters.py` and `_data/adopters.yml` to carry the "Use-Case" text from -`ADOPTERS.md`, and show it as a tooltip or an expandable card on each logo. This -turns the logo wall into short, attributed testimonials at no authoring cost. - -Done when: hovering or expanding a logo shows that adopter's use case. - -### Create an adopters page - -Create a `/adopters/` or `/case-studies/` page that renders the full adopters -table (type, name, since, use case) and links to the CNCF case studies, so -evaluators have a single place for adoption evidence. Add it to -`_data/site_nav_pages.yml`. - -Done when: the page is in the site navigation and lists every adopter. - -### Add a Governance section to the Community page - -Add a "Governance" section to the Community page that states in two or three -sentences how KubeVirt is governed (CNCF incubating project, maintainer group, -SIGs and working groups, lazy consensus with maintainer votes) and links -`GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in -`kubevirt/community`. - -Done when: a visitor can find the governance documents from the Community page. - -### Index non-blog pages in site search and cross-link the two searches - -Extend the lunr index in `_layouts/search.html` to include `site.pages` in -addition to `site.posts`, so non-blog pages are searchable. Add a link from the -main site's search page to the user guide search, and from the user guide's -search results to the main site's, so users can find documentation from either -entry point. - -Done when: a search for "installation" on `kubevirt.io` returns the relevant -page. - -### Add blog categories beyond news and uncategorized - -Add a category or tag scheme (for example release, feature, community, user -story) and backfill recent posts, so the blog index can filter by type and -adopter stories can be listed together. - -Done when: the blog index offers category filtering and recent posts are tagged. - -### Point vendor logos at KubeVirt-specific pages - -For each entry in `ADOPTERS.md` whose link is a corporate homepage, ask the -vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, -and update the link. Drop the logo from the Vendors section if no such page -exists. - -Done when: every vendor logo links to a page that mentions KubeVirt. - -### Publish a short brand reference - -Publish a brand reference, in this repository or in `kubevirt/community`, that -lists the canonical logo files (icon and horizontal wordmark), the hex values of -the `$kv-color--green-*` scale, and the approved typefaces. Have -`docs/stylesheets/extra.css` in the user guide cite that reference in a comment -so the two sites stay aligned when the palette changes. - -Done when: both repositories point at the same brand reference. diff --git a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md deleted file mode 100644 index 20848d7c..00000000 --- a/analyses/2026/kubevirt/issues/U-fix-navigation-gaps.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: - Fix navigation gaps and reorganize the user guide information architecture -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -Several pages are unreachable or misplaced in the navigation, and page titles in -the Storage section describe APIs rather than what a reader accomplishes. The -Plugins page is reachable only from the deprecated Hook Sidecar page, a -byte-identical duplicate of the Windows virtio drivers page is unlisted, Release -Notes sits in the middle of the main navigation, and the API reference has no -home in the guide. - -The sub-issues below fix the gaps first and then make the structure read as a -progression from concepts through administration, workloads, and infrastructure -layers. Every subdirectory under `docs/` has a `.nav.yml` that controls page -order; when a file name changes, add a redirect in `mkdocs.yml`. - -## Sub-issues - -### Add the Plugins page and delete duplicate Windows virtio drivers page - -Add `plugins.md` to `docs/cluster_admin/.nav.yml` so the Plugins page is -discoverable from somewhere other than the deprecated Hook Sidecar page. - -Delete `docs/compute/windows_virtio_drivers.md`, which is a byte-identical -unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Add a -redirect in `mkdocs.yml` if the old URL was ever published. - -Done when: Plugins appears in the Cluster Administration navigation and only one -Windows virtio drivers page exists. - -### Move Release Notes out of the middle of the main navigation - -In `docs/.nav.yml`, move Release Notes to the end of the list or into a top-bar -link, so the section list reads Welcome, Architecture, Getting Started, Cluster -Administration, User Workloads, Compute, Network, Storage, then Contributing, -Release Notes, and Virtualization Debugging. - -Done when: the main navigation reads as a progression without the Release Notes -interruption. - -### Group legacy workload mechanisms under a Legacy heading - -In `docs/user_workloads/.nav.yml`, reorganize the Workloads sub-group so current -mechanisms (instance types, VirtualMachine Templates, pools) come first and -legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) sit -under a clearly labeled "Legacy" heading or at the end. - -Done when: a reader sees the recommended mechanism before any deprecated one. - -### Add a landing page to each of the Compute, Network, and Storage sections - -Add a brief `index.md` landing page to `docs/compute/`, `docs/network/`, and -`docs/storage/` that explains what the section covers and groups its pages by -task. For example, Storage: provisioning disks, importing images, snapshots and -backup, moving data between clusters. Add each landing page to its `.nav.yml`. - -Done when: each section opens on a page that orients the reader. - -### Rename API-centric page titles to user goals - -Rename page titles so they state what the reader accomplishes, for example: - -- "Clone API" to "Cloning VirtualMachines" -- "Export API" to "Exporting VirtualMachines and volumes" -- "Snapshot Restore API" to "Snapshotting and restoring VirtualMachines" -- "Migration Controller" to a title that states what the reader accomplishes - with it - -Change titles in the page front matter and `.nav.yml` first. If you also rename -files, add redirects in `mkdocs.yml`. - -Done when: no Storage page title ends in "API". - -### Give the API reference a visible home in the user guide - -Add a navigation entry or a short landing page that links to the API reference -at `https://kubevirt.io/api-reference/`, so readers do not need to know it is -published from a separate repository. - -Done when: a reader can reach the API reference from the guide's navigation. - -### Remove or archive legacy installation content - -Verify with the maintainers whether the OKD Service Catalog APB and k3OS -installation paths on `docs/cluster_admin/installation.md` are still supported. -Remove the paths that are not, and update the OpenShift 4.10 documentation links -to a current version or a version-independent URL. - -Done when: the Installation page references only supported platforms and current -links. diff --git a/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md b/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md deleted file mode 100644 index 659c5cea..00000000 --- a/analyses/2026/kubevirt/issues/U-inclusive-language-updates.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: Remove legacy branch names and minimizing language from the user guide -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -The guide links to the API reference at `/master/` paths fourteen times, uses -`master` as an example node name, and relies on minimizing words such as -"simply", "just", and "easily" that tell a struggling reader the task should -have been easy. Fixing the links and example is quick. Rewording the prose is a -page-by-page pass, and an automated check keeps new occurrences out. - -The style-guide rule that discourages minimizing language is tracked in the -contributor guide issue. - -## Sub-issues - -### Update legacy branch-name links and the Presets example - -- Update the 14 links to `kubevirt.io/api-reference/master/...` to the `/main/` - path, or to a specific version path such as `/v1.9.0/`. -- On the Presets page (`docs/user_workloads/presets.md`), replace the - `kubevirt.io/nodeName: master` example with a neutral node name such as - `node01`, or remove the example, since the page documents a deprecated - feature. - -Done when: `grep -r "api-reference/master" docs/` returns nothing and the -Presets page uses a neutral node name. - -### Reword minimizing language on the five pages with the most occurrences - -On Live Migration, Windows Virtio Drivers, Node Assignment, vsock, and Disks and -Volumes, delete "simply", "just", "of course", and "obviously" where they add -nothing, and replace "easy" or "easily" with a concrete statement of what the -step requires. For example, change "can be easily cancelled" to "can be -cancelled by deleting the migration object". - -Done when: none of the five pages contains the listed words in a minimizing -sense. - -### Reword minimizing language across the remaining pages - -Apply the same pass to the rest of `docs/`. Use -`grep -rniw "simply\|just\|easy\|easily\|obviously\|of course" docs/` to find -occurrences and review each in context; some uses of "just" are legitimate. - -Done when: the grep returns only legitimate uses. - -### Prefer "cancel" over "abort" in Live Migration prose - -On the Live Migration page (`docs/compute/live_migration.md`), use "cancel" in -the prose while continuing to show the `Abort Requested` and `Abort Status` -field names as they appear in `kubectl` output. Ask the KubeVirt API maintainers -whether those VirtualMachineInstanceMigration status fields are candidates for a -"cancel" alias in a future API version, and record the answer in the issue. - -Done when: the prose says "cancel" and field names are shown in code formatting. - -### Add an automated check for minimizing language - -Add a check to the Makefile and the Prow pre-submit, alongside -`make check_spelling`, that flags minimizing and non-recommended language in -pull requests. Use Vale with the `write-good` style or a grep-based check. - -Done when: a pull request that adds "simply" fails the check. - -### Use tagged or permalink URLs for upstream project links - -Where the guide links to libvirt, cri-tools, vhost-md, or kubevirt-ansible files -on a `master` branch, change the links to a tag or commit permalink so the -branch name is not repeated in the guide and the link survives a default-branch -rename. - -Done when: no outbound link in `docs/` includes `/master/`. diff --git a/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md b/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md deleted file mode 100644 index a44cc300..00000000 --- a/analyses/2026/kubevirt/issues/U-mkdocs-improvements.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Apply low-effort mkdocs.yml and build configuration improvements -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -Several one-line configuration changes in `mkdocs.yml` and `netlify.toml` would -noticeably improve the guide: copyable code blocks, better search, social links -in the header and footer, correct logo alt text, reproducible builds, and no -indexing of preview deploys. None requires content changes. Each sub-issue is a -single pull request of configuration edits plus a local build (`mkdocs serve`) -to confirm the result. - -## Sub-issues - -### Enable code copy and search features in the theme - -Under `theme.features` in `mkdocs.yml`, add: - -- `content.code.copy`, which adds a copy button to every code block. -- `search.suggest`, `search.highlight`, and `search.share`, which improve search - usability. - -Done when: a copy button appears on code blocks and search shows suggestions and -highlights terms. - -### Add repository and social links to every page - -In `mkdocs.yml`, set `repo_url` to the `kubevirt/user-guide` repository and add -an `extra.social` block with the project's GitHub, Slack, mailing list, and -`kubevirt.io` links. These appear in the header and footer on every page instead -of only in the "Getting help" list on the Welcome page. - -Done when: the header shows the repository link and the footer shows the social -icons. - -### Set the logo alt text and remove unused configuration and assets - -- Set the logo alt text to "KubeVirt" by adding `extra.homepage` or a custom - `overrides/partials/logo.html`. -- Remove the unsupported top-level `site_favicon` key from `mkdocs.yml`; MkDocs - ignores it and the active favicon is already set under `theme.favicon`. -- Remove the unused legacy assets `asciibinder-logo-horizontal.png`, - `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. - -Done when: the logo has alt text, `mkdocs build --strict` reports no unknown -keys, and `docs/assets` contains only current brand assets. - -### Make preview builds reproducible and non-indexable - -- Pin the MkDocs package versions in `netlify.toml`, or add a - `requirements.txt`, so preview builds match the Prow image. -- Remove the obsolete `sed` line in `netlify.toml` that rewrites - `site_url: https://kubevirt.io/docs`; `mkdocs.yml` already sets `site_url` to - `https://kubevirt.io/user-guide`. -- Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file - or a `[context.deploy-preview]` and `[context.branch-deploy]` section in - `netlify.toml`, rather than relying on Netlify defaults. - -Done when: a deploy preview builds with pinned versions and returns the -`noindex` header. diff --git a/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md deleted file mode 100644 index b99169a8..00000000 --- a/analyses/2026/kubevirt/issues/U-publish-versioned-docs.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Document the versioning model and publish versioned documentation -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - -## Overview - -The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but -nothing explains what they are for, which one is published, or when a change on -`main` needs a cherry-pick. Only one version of the guide is published, so users -on an older KubeVirt release read documentation for features they do not have. -The release-notes regeneration step and the project's localization position are -also undocumented. - -The sub-issues below record the versioning workflow, publish versioned -documentation with a version selector, and close the remaining -documentation-process gaps. Confirm the intended workflow with the maintainers -first; the `-devel` branches exist for 1.7 and 1.8 but not 1.9, which suggests -the process has drifted. - -## Sub-issues - -### Document the content versioning model - -In `CONTRIBUTING.md`, and summarized on the Contributing page, state what the -`release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are -cut relative to a KubeVirt release, which branch is published, and how a -contributor decides whether a change on `main` needs a cherry-pick. Confirm the -intended workflow with the maintainers before writing. - -Done when: a contributor can decide from the text alone whether to cherry-pick. - -### Publish versioned documentation with a version selector - -Publish versioned documentation using either `mike` with the theme's -`extra.version.provider: mike` setting, or a build per release branch published -under a `/vX.Y/` path. Publish at least the supported N, N-1, and N-2 minors -alongside `latest`. Start by prototyping the build locally and documenting the -release-time steps; the Netlify and Prow changes can follow in a second pull -request. - -Done when: the published guide shows a version selector with at least three -versions. - -### Document the release-notes update process - -Record when `update_changelog.sh` is run, by whom, and how the result is -reviewed, so the Release Notes page continues to be regenerated after maintainer -turnover. Add this to `CONTRIBUTING.md` next to the versioning model. - -Done when: the process is written down and names a responsible role. - -### Add a localization statement - -Add a short "Localization" statement to `CONTRIBUTING.md` that records the -project's current position: English only, translations not currently accepted, -or translations welcome via a stated process. If translations are anticipated -within the next few releases, move content to `docs/en/` now and configure the -`mkdocs-static-i18n` plugin so the redirects and `.nav.yml` files only need to -change once. - -Done when: a prospective translator knows whether and how to contribute. - -### Ask about a site-wide search across the user guide, API reference, and quickstarts - -Ask the KubeVirt website maintainers whether the API reference and quickstarts -can be indexed by the same search as the user guide, for example by moving the -user guide search to a site-wide index. Record the decision in this issue and, -if agreed, open a follow-up with the implementation plan. - -Done when: a decision is recorded. diff --git a/analyses/2026/kubevirt/issues/add-troubleshooting-page.md b/analyses/2026/kubevirt/issues/add-troubleshooting-page.md deleted file mode 100644 index 420e3a1c..00000000 --- a/analyses/2026/kubevirt/issues/add-troubleshooting-page.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Add a user-facing Troubleshooting page -labels: [high, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - - - -## Description - -The guide has no page a user can turn to when something goes wrong. The -Virtualization Debugging section is written for developers who need to attach -`gdb` or `strace` to QEMU, and the troubleshooting notes that do exist for users -are embedded in unrelated pages such as Accessing Virtual Machines and Memory -Dump. - -Add a Troubleshooting page, separate from Virtualization Debugging, that lists -common symptoms with likely causes and links to the fix. Start with these -symptoms: - -- A VirtualMachineInstance stuck in `Scheduling` or `Pending`. -- A failed live migration. -- Console or VNC connection errors. -- Missing `qemu-guest-agent` data. - -For each symptom, give the `kubectl` or `virtctl` command that reveals the -cause, the two or three most likely causes, and a link to the page that explains -the fix. Move the troubleshooting notes from Accessing Virtual Machines and -Memory Dump onto this page, or link to them from it. Add the page to -`docs/.nav.yml` near Virtualization Debugging and link to it from the Getting -Started page. - -## What you expected - -A user who hits a common failure can find a symptom-oriented page in the guide -that leads them to the cause and the fix without reading the developer debugging -section. - -## URL - -- https://kubevirt.io/user-guide/debug_virt_stack/debug/ - (`docs/debug_virt_stack/debug.md`) -- https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ - (`docs/user_workloads/accessing_virtual_machines.md`) -- https://kubevirt.io/user-guide/compute/memory_dump/ - (`docs/compute/memory_dump.md`) - -## Additional context - -Keep the first version small. Four symptoms with accurate causes are more useful -than a long list; the page can grow as users report more. diff --git a/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md b/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md deleted file mode 100644 index c15906c2..00000000 --- a/analyses/2026/kubevirt/issues/fix-footer-cncf-compliance.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Bring the user guide footer and repository files into CNCF compliance -labels: [urgent, help wanted] -repo: https://github.com/kubevirt/user-guide/issues ---- - - - -## Description - -The CNCF website guidelines require every project property to show the Linux -Foundation copyright line, the project's CNCF maturity statement, the CNCF logo, -and a link to the LF Projects policies. The user guide footer shows none of -these, and the repository has no root `CODE_OF_CONDUCT.md`. - -Make these changes: - -1. In `mkdocs.yml`, set - `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"`. -2. Add `overrides/partials/copyright.html` (or a `footer.html` override) that - appends "We are a Cloud Native Computing Foundation incubating project", the - CNCF logo linked to `https://cncf.io`, and a link to - `https://lfprojects.org/policies/` for trademark and terms. Match the wording - and links used in the main website footer so the two properties read as one. -3. Add a root `CODE_OF_CONDUCT.md` that links to the `kubevirt/community` code - of conduct, so the file is present where the CNCF checklist expects it rather - than only inherited from the organization default. -4. Add a note to the README naming the file to edit when the project's CNCF - maturity status changes, so the footer statement does not go stale. - -## What you expected - -The user guide footer shows the same copyright, maturity statement, CNCF logo, -and policy link as `kubevirt.io`, and the repository root contains a code of -conduct. - -## URL - -- https://kubevirt.io/user-guide/ (footer on every page) -- `mkdocs.yml`, `overrides/`, `README.md` in the repository root - -## Additional context - -The theme's `custom_dir` must be set to `overrides` in `mkdocs.yml` for partial -overrides to take effect; check whether it already is. From b62f9a55f7df01dd3dbf698eb6583d0117051479 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 02:50:11 -0700 Subject: [PATCH 07/31] line lenght adjustments Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 242 +----------------- .../issues/9001-add-getting-started-page.md | 28 +- .../kubevirt/issues/9002-rewrite-basic-use.md | 36 ++- .../issues/9003-fix-welcome-page-links.md | 25 +- .../9004-restructure-installation-page.md | 32 ++- .../9005-create-installing-virtctl-page.md | 28 +- .../issues/9006-enable-code-copy-search.md | 18 +- .../issues/9007-convert-shell-code-blocks.md | 27 +- .../issues/9008-fix-navigation-orphans.md | 34 ++- .../issues/9009-add-section-landing-pages.md | 28 +- .../issues/9010-rename-api-page-titles.md | 36 ++- ...9011-remove-legacy-installation-content.md | 31 ++- .../9012-document-virtualmachinebackup-api.md | 38 ++- .../issues/9013-document-v19-features.md | 45 +++- .../issues/9014-create-virtctl-reference.md | 29 ++- .../issues/9015-add-feature-gate-table.md | 27 +- .../issues/9016-add-troubleshooting-page.md | 31 ++- ...17-standardize-feature-state-admonition.md | 38 ++- .../issues/9018-document-versioning-model.md | 45 +++- .../issues/9019-publish-versioned-docs.md | 30 ++- .../issues/9020-expand-contributing-guide.md | 32 ++- .../kubevirt/issues/9021-add-style-guide.md | 38 ++- .../issues/9022-add-pull-request-template.md | 29 ++- .../kubevirt/issues/9023-add-owners-files.md | 30 ++- .../issues/9024-give-docs-sig-home.md | 32 ++- .../kubevirt/issues/9025-triage-open-prs.md | 31 ++- .../issues/9026-add-maintainers-file.md | 41 ++- .../issues/9027-reword-minimizing-language.md | 28 +- .../kubevirt/issues/9028-add-ci-doc-checks.md | 34 ++- .../9029-fix-legacy-master-references.md | 45 ++-- .../issues/9030-add-community-page.md | 34 ++- .../9031-add-community-adoption-links.md | 29 ++- .../issues/9032-add-footer-social-links.md | 27 +- .../issues/9033-fix-logo-and-unused-assets.md | 25 +- .../issues/9034-add-contributing-overview.md | 32 ++- .../issues/9035-add-help-and-vep-guidance.md | 30 ++- .../kubevirt/issues/9036-link-issue-lists.md | 27 +- .../9037-add-first-change-walkthrough.md | 30 ++- .../9038-standardize-good-first-issue.md | 27 +- .../issues/9039-triage-issue-backlog.md | 33 ++- .../issues/9040-add-governance-section.md | 34 ++- .../issues/9041-document-content-boundary.md | 24 +- .../issues/9042-add-api-reference-link.md | 28 +- .../issues/9043-audit-kubevirt-docs.md | 42 ++- .../kubevirt/issues/9044-audit-cdi-docs.md | 32 ++- .../issues/9045-decide-converge-toolchains.md | 38 ++- .../kubevirt/issues/9046-fix-guide-footer.md | 32 ++- .../issues/9047-fix-website-footer.md | 31 ++- .../issues/9048-fix-contrast-and-colors.md | 33 ++- .../kubevirt/issues/9049-fix-mobile-tables.md | 40 ++- .../issues/9050-split-disks-networks-pages.md | 35 ++- .../9051-split-migration-release-notes.md | 28 +- .../issues/9052-publish-brand-reference.md | 28 +- .../kubevirt/issues/9053-add-adopters-page.md | 27 +- .../issues/9054-show-adopter-use-cases.md | 32 ++- .../issues/9055-add-blog-categories.md | 26 +- .../issues/9056-enable-guide-analytics.md | 32 ++- .../9057-fix-robots-and-site-analytics.md | 30 ++- .../issues/9058-fix-guide-preview-builds.md | 29 ++- .../2026/kubevirt/issues/9059-unify-search.md | 29 ++- .../9060-document-site-infrastructure.md | 30 ++- .../U-9061-create-getting-started-path.md | 26 +- .../issues/U-9062-fix-navigation-gaps.md | 26 +- .../U-9063-fill-feature-coverage-gaps.md | 18 +- .../issues/U-9064-publish-versioned-docs.md | 18 +- .../issues/U-9065-build-contributor-guide.md | 6 +- .../U-9066-improve-contributing-page.md | 23 +- .../U-9067-document-community-channels.md | 22 +- .../U-9068-inclusive-language-updates.md | 17 +- .../U-9069-accessibility-improvements.md | 18 +- .../issues/U-9070-fix-website-compliance.md | 19 +- .../issues/U-9071-enable-analytics-seo.md | 20 +- .../issues/U-9072-document-site-ownership.md | 23 +- 73 files changed, 1571 insertions(+), 807 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 3e3386d2..30a97584 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -2,247 +2,7 @@ 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. -## Issues - -| Issue | Title | Label | File | -|---|---|---|---| -| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | -| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | -| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | -| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | -| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | -| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | -| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | -| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | -| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | -| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | -| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | -| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | -| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | -| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | -| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | -| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | -| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | -| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | -| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | -| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | -| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | -| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | -| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | -| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | -| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | -| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | -| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | -| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | -| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | -| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | -| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | -| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | -| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | -| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | -| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | -| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | -| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | -| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | -| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | -| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | -| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | -| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | -| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | -| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | -| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | -| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | -| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | -| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | -| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | -| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | -| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | -| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | -| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | -| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | -| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | -| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | -| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | -| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | -| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | -| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | -| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | -| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | -| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | -| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | -| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | -| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | -| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | -| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | -| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | -| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | -| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | -| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | - -## Umbrella issues - -| Umbrella | Label | Sub-issues | -|---|---|---| -| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | -| #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | -| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | -| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | -| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | -| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | -| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | -| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | -| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | -| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | -| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | -| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | - -Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. - -## Recommendation mapping - -| # | Section | Area | CSV priority | Issue(s) | -|---|---|---|---|---| -| 1 | Project Documentation | Information architecture | 2 - High | #9001 | -| 2 | Project Documentation | Information architecture | 2 - High | #9002 | -| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | -| 5 | Project Documentation | Information architecture | 2 - High | #9014 | -| 6 | Project Documentation | Information architecture | 2 - High | #9015 | -| 7 | Project Documentation | Information architecture | 2 - High | #9016 | -| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | -| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 11 | Project Documentation | Information architecture | 2 - High | #9011 | -| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 14 | Project Documentation | New user content | 2 - High | #9001 | -| 15 | Project Documentation | New user content | 2 - High | #9004 | -| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | -| 17 | Project Documentation | New user content | 2 - High | #9004 | -| 18 | Project Documentation | New user content | 2 - High | #9005 | -| 19 | Project Documentation | New user content | 2 - High | #9002 | -| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | -| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | -| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | -| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | -| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | -| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | -| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | -| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | -| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | -| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | -| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | -| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | -| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | -| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | -| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | -| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | -| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | -| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | -| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | -| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | -| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | -| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | -| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | -| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | -| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | -| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | -| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | -| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | -| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | -| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | -| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | -| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | -| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | -| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | -| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | -| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | -| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | -| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | -| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | -| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | -| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | -| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | -| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | -| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | -| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | -| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | -| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | -| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | -| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | -| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | -| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | -| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | -| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | -| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | -| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | -| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | -| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | -| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | -| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | -| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | -| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | -| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | -| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | -| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | -| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | -| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | -| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | -| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | -| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | -| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | -| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | -| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | -| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | -| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | -| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | - -## Priority adjustments - -No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: - -| Issue | Label | Recommendations raised (original ranking) | Reason | -|---|---|---|---| -| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | -| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | -| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | -| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | -| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | -| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | -| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | -| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | -| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | -| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | -| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | -| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | -| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | -| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | -| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | -| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | -| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | -| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | -| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | -| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | +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 diff --git a/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md b/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md index 94f0e487..0826bc60 100644 --- a/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md +++ b/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md @@ -6,9 +6,15 @@ 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. +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: +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). @@ -17,11 +23,17 @@ Add a `docs/getting_started.md` page and place it immediately after Architecture 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. +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. +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 @@ -31,6 +43,10 @@ A new user opens one page after Architecture and reaches a running, accessible V ## 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`. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md b/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md index 1c7f6288..e31b1cd7 100644 --- a/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md +++ b/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md @@ -6,20 +6,33 @@ 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. +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: +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. +- 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. +- 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`. +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. +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 @@ -29,6 +42,11 @@ A new user copies one manifest, runs four commands, and sees a VirtualMachine st ## 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). +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). +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). diff --git a/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md b/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md index 91e85c8b..4d5a823a 100644 --- a/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md +++ b/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md @@ -6,16 +6,25 @@ 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. +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. +- 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. +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 @@ -24,6 +33,10 @@ A new reader sees a "Start here" link before the section list and can reach the ## 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. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md b/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md index cc5cb758..534479ee 100644 --- a/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md +++ b/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md @@ -6,18 +6,29 @@ 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. +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. +- 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. +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 @@ -26,6 +37,11 @@ The first screen of the page contains the steps needed to install KubeVirt and v ## 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. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md b/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md index eb908012..a98add29 100644 --- a/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md +++ b/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md @@ -6,20 +6,29 @@ 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. +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. +- 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. +- 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. +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 @@ -28,6 +37,11 @@ A reader on any supported operating system and CPU architecture finds the right ## 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. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md b/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md index d211bda8..da556905 100644 --- a/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md +++ b/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md @@ -6,7 +6,9 @@ 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`. +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`: @@ -15,11 +17,13 @@ Add the following entries to the `theme.features` list in `mkdocs.yml`: - `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. +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. +Every code block has a copy button, and search suggests terms, highlights +matches on the result page, and offers a shareable link. ## URL @@ -28,6 +32,10 @@ Every code block has a copy button, and search suggests terms, highlights matche ## 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. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md b/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md index 7be64563..bd443a89 100644 --- a/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md +++ b/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md @@ -6,7 +6,11 @@ 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. +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: @@ -15,13 +19,17 @@ Convert the blocks in this order, one pull request per group: For each block: -- Replace the indented block with a fenced block with the `shell` language tag and remove the `$` prompt. +- 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. +- 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. +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 @@ -31,10 +39,15 @@ Commands on the converted pages paste directly into a terminal, and output is vi - 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/` +- 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. +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). +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). diff --git a/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md b/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md index 6fc7a725..a04117d9 100644 --- a/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md +++ b/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md @@ -8,29 +8,45 @@ repo: https://github.com/kubevirt/user-guide/issues Three navigation problems make content hard to find or confusing: -- `docs/cluster_admin/plugins.md` is not listed in `docs/cluster_admin/.nav.yml`, so the Plugins page is reachable only from the deprecated Hook Sidecar page. -- `docs/compute/windows_virtio_drivers.md` is an unlisted duplicate of `docs/user_workloads/windows_virtio_drivers.md`. Verify the files are identical (for example with `diff`). -- Release Notes sits in the middle of the top-level list in `docs/.nav.yml`, between Storage and Contributing, which breaks the progression from concepts through administration, workloads, and infrastructure. +- `docs/cluster_admin/plugins.md` is not listed in + `docs/cluster_admin/.nav.yml`, so the Plugins page is reachable only from the + deprecated Hook Sidecar page. +- `docs/compute/windows_virtio_drivers.md` is an unlisted duplicate of + `docs/user_workloads/windows_virtio_drivers.md`. Verify the files are + identical (for example with `diff`). +- Release Notes sits in the middle of the top-level list in `docs/.nav.yml`, + between Storage and Contributing, which breaks the progression from concepts + through administration, workloads, and infrastructure. Make these changes: 1. Add `plugins.md` to `docs/cluster_admin/.nav.yml`. -2. Delete `docs/compute/windows_virtio_drivers.md` and add a redirect in `mkdocs.yml` to the User Workloads page if the old URL was ever published. -3. Move Release Notes to the end of the list in `docs/.nav.yml`, or expose it as a top-bar link. +2. Delete `docs/compute/windows_virtio_drivers.md` and add a redirect in + `mkdocs.yml` to the User Workloads page if the old URL was ever published. +3. Move Release Notes to the end of the list in `docs/.nav.yml`, or expose it as + a top-bar link. ## What you expected -Every page in `docs/` is reachable from the navigation, no duplicate page exists, and the top-level sections read in a logical order with Release Notes at the end. +Every page in `docs/` is reachable from the navigation, no duplicate page +exists, and the top-level sections read in a logical order with Release Notes at +the end. ## URL - https://kubevirt.io/user-guide/cluster_admin/plugins/ - https://kubevirt.io/user-guide/user_workloads/windows_virtio_drivers/ - https://kubevirt.io/user-guide/release_notes/ -- `docs/.nav.yml`, `docs/cluster_admin/.nav.yml`, `docs/compute/windows_virtio_drivers.md`, `mkdocs.yml` +- `docs/.nav.yml`, `docs/cluster_admin/.nav.yml`, + `docs/compute/windows_virtio_drivers.md`, `mkdocs.yml` ## Additional context -This work is a quick win. Check the deployed site to see whether `/compute/windows_virtio_drivers/` was ever served before you decide on the redirect. +This work is a quick win. Check the deployed site to see whether +`/compute/windows_virtio_drivers/` was ever served before you decide on the +redirect. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md index 77ff4bee..ee79d332 100644 --- a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -6,30 +6,44 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Compute, Network, and Storage sections each hold 10 to 20 pages with no introduction. Readers see a flat list and cannot tell which page matches their task. +The Compute, Network, and Storage sections each hold 10 to 20 pages with no +introduction. Readers see a flat list and cannot tell which page matches their +task. -Add a short landing page to each section, `docs/compute/index.md`, `docs/network/index.md`, and `docs/storage/index.md`, and list it first in the section's navigation. Each page explains in two or three sentences what the section covers, then groups its pages by task with a one-line description per link. For example, the Storage page uses these groups: +Add a short landing page to each section, `docs/compute/index.md`, +`docs/network/index.md`, and `docs/storage/index.md`, and list it first in the +section's navigation. Each page explains in two or three sentences what the +section covers, then groups its pages by task with a one-line description per +link. For example, the Storage page uses these groups: - Provisioning disks - Importing images - Snapshots and backup - Moving data between clusters -Propose equivalent task groups for Compute (for example CPU and memory, live migration, devices) and Network (for example interfaces, services, binding plugins). Ask a maintainer to confirm the groupings. +Propose equivalent task groups for Compute (for example CPU and memory, live +migration, devices) and Network (for example interfaces, services, binding +plugins). Ask a maintainer to confirm the groupings. ## What you expected -Selecting a section shows a page that explains its scope and points to the right page for each common task. +Selecting a section shows a page that explains its scope and points to the right +page for each common task. ## URL - https://kubevirt.io/user-guide/compute/ - https://kubevirt.io/user-guide/network/ - https://kubevirt.io/user-guide/storage/ -- New files `docs/compute/index.md`, `docs/network/index.md`, `docs/storage/index.md`; the existing `.nav.yml` files in each directory +- New files `docs/compute/index.md`, `docs/network/index.md`, + `docs/storage/index.md`; the existing `.nav.yml` files in each directory ## Additional context -Page renames in #9010 change some link titles, so write the landing pages with the final titles or update them afterward. +Page renames in #9010 change some link titles, so write the landing pages with +the final titles or update them afterward. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index 263a8296..a5920261 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -6,24 +6,32 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Several page titles name an API instead of the task the reader wants to do, and the User Workloads "Workloads" group mixes current and legacy mechanisms. +Several page titles name an API instead of the task the reader wants to do, and +the User Workloads "Workloads" group mixes current and legacy mechanisms. -Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: +Rename these titles, changing the first H1 in each file and the `.nav.yml` +entry: -| Current title | Proposed title | -| --- | --- | -| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | -| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | -| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | +| Current title | Proposed title | +| ------------------------------------------------------------- | ------------------------------------------------ | +| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | +| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | +| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | | Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | -Choose the last title after reading the page; ask the maintainers if the purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update inbound links. +Choose the last title after reading the page; ask the maintainers if the purpose +is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update +inbound links. -Then reorder the "Workloads" group in `docs/user_workloads/.nav.yml`. List current mechanisms (instance types, VirtualMachine Templates, pools) first. Place legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) under a clearly labeled "Legacy" heading, or at the end of the group. +Then reorder the "Workloads" group in `docs/user_workloads/.nav.yml`. List +current mechanisms (instance types, VirtualMachine Templates, pools) first. +Place legacy or deprecated pages (presets, OpenShift Templates, Hook Sidecar) +under a clearly labeled "Legacy" heading, or at the end of the group. ## What you expected -Titles tell readers what they can accomplish, and the Workloads group leads with current mechanisms while legacy pages are labeled as such. +Titles tell readers what they can accomplish, and the Workloads group leads with +current mechanisms while legacy pages are labeled as such. ## URL @@ -36,6 +44,10 @@ Titles tell readers what they can accomplish, and the Workloads group leads with ## Additional context -Prefer keeping file names unchanged to avoid broken inbound links, unless the rename adds clear value. +Prefer keeping file names unchanged to avoid broken inbound links, unless the +rename adds clear value. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md b/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md index e9d5292d..2c4ada78 100644 --- a/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md +++ b/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md @@ -6,19 +6,29 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Installation page keeps instructions for platforms and tools that may no longer be supported, and its OKD instructions link to OpenShift 4.10 documentation, which is out of date. Readers cannot tell whether these paths still work. +The Installation page keeps instructions for platforms and tools that may no +longer be supported, and its OKD instructions link to OpenShift 4.10 +documentation, which is out of date. Readers cannot tell whether these paths +still work. -Review these sections of `docs/cluster_admin/installation.md` with the maintainers: +Review these sections of `docs/cluster_admin/installation.md` with the +maintainers: -- "From Service Catalog as an APB" under "Installing KubeVirt on OKD": Is the OKD Service Catalog APB path still supported? +- "From Service Catalog as an APB" under "Installing KubeVirt on OKD": Is the + OKD Service Catalog APB path still supported? - "Installing KubeVirt on k3OS": Is k3OS still a supported platform? -- The OpenShift 4.10 links, including the SCC link: Which current version should the page link to, or is a version-independent URL available? +- The OpenShift 4.10 links, including the SCC link: Which current version should + the page link to, or is a version-independent URL available? -Then act on the answers. Delete unsupported sections, or move them to an "Archived" page with a clear notice that they are not maintained. Update the OpenShift links to the current version or a version-independent URL. Verify that every remaining link in the page resolves. +Then act on the answers. Delete unsupported sections, or move them to an +"Archived" page with a clear notice that they are not maintained. Update the +OpenShift links to the current version or a version-independent URL. Verify that +every remaining link in the page resolves. ## What you expected -The Installation page describes only paths that KubeVirt supports today, and every external link points to current documentation. +The Installation page describes only paths that KubeVirt supports today, and +every external link points to current documentation. ## URL @@ -27,6 +37,11 @@ The Installation page describes only paths that KubeVirt supports today, and eve ## Additional context -The maintainers must answer the support questions before you delete content. This work overlaps with the restructure in #9004, which moves the same sections; agree on the order of the two pull requests to avoid conflicts. +The maintainers must answer the support questions before you delete content. +This work overlaps with the restructure in #9004, which moves the same sections; +agree on the order of the two pull requests to avoid conflicts. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md b/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md index 0f75375a..0a86b1cd 100644 --- a/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md +++ b/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md @@ -6,21 +6,31 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The `VirtualMachineBackup` API, introduced in v1.9, appears only in `docs/release_notes.md`. Users who read the Storage section find snapshots and export but no mention of backup, so they cannot discover or use the feature. - -Add a section to an existing Storage page, or a new `docs/storage/` page added to `docs/storage/.nav.yml`, that covers: - -- What a VirtualMachineBackup does and how it differs from a VirtualMachineSnapshot and a VMExport. -- A minimal VirtualMachineBackup manifest and the `kubectl` commands to create it and watch its progress. -- The conditions a backup reports (`Progressing`, `Complete`, and `Failed`) and what each means. -- Prerequisites, such as feature gates and storage requirements. Ask the maintainers which gates and requirements apply. +The `VirtualMachineBackup` API, introduced in v1.9, appears only in +`docs/release_notes.md`. Users who read the Storage section find snapshots and +export but no mention of backup, so they cannot discover or use the feature. + +Add a section to an existing Storage page, or a new `docs/storage/` page added +to `docs/storage/.nav.yml`, that covers: + +- What a VirtualMachineBackup does and how it differs from a + VirtualMachineSnapshot and a VMExport. +- A minimal VirtualMachineBackup manifest and the `kubectl` commands to create + it and watch its progress. +- The conditions a backup reports (`Progressing`, `Complete`, and `Failed`) and + what each means. +- Prerequisites, such as feature gates and storage requirements. Ask the + maintainers which gates and requirements apply. - Links to the Snapshot Restore API and Export API pages. -Take the facts from the release notes entries for VirtualMachineBackup and confirm technical details with the feature author. Phrase anything you cannot confirm as a question to the maintainers. +Take the facts from the release notes entries for VirtualMachineBackup and +confirm technical details with the feature author. Phrase anything you cannot +confirm as a question to the maintainers. ## What you expected -A user can find the Backup API from the Storage section and run a first backup by following the page. +A user can find the Backup API from the Storage section and run a first backup +by following the page. ## URL @@ -30,6 +40,10 @@ A user can find the Backup API from the Storage section and run a first backup b ## Additional context -Related v1.9 documentation gaps are in #9013. If a Storage landing page exists (#9009), link the new content from it. +Related v1.9 documentation gaps are in #9013. If a Storage landing page exists +(#9009), link the new content from it. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9013-document-v19-features.md b/analyses/2026/kubevirt/issues/9013-document-v19-features.md index 5dbfa3f1..9fa62e8d 100644 --- a/analyses/2026/kubevirt/issues/9013-document-v19-features.md +++ b/analyses/2026/kubevirt/issues/9013-document-v19-features.md @@ -1,22 +1,37 @@ --- -title: Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression #9013 +title: Document the CrossArchitectureVirtualization gate, PortRanges, and + migration compression #9013 labels: [high, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Description -Three v1.9 features appear only in `docs/release_notes.md`, so users cannot find them in the feature pages. Add a section for each: - -- **`CrossArchitectureVirtualization` feature gate** (Alpha): Add a section to a Compute page or to `docs/cluster_admin/activating_feature_gates.md`. Explain that VMs can run on nodes with a different architecture through QEMU software emulation (TCG), that the scheduler prefers native-architecture nodes and falls back to emulation, and how to enable the gate. -- **Masquerade `PortRanges`** (Alpha, guarded by the `PortRangesSpec` feature gate): Add a section to `docs/network/interfaces_and_networks.md` that shows how to define port ranges on a masquerade interface, with an example and the gate to enable. -- **MigrationPolicy compression**: Add a section to `docs/cluster_admin/migration_policies.md` that explains the `.spec.experimental.compression` field. It compresses the live migration data stream, and only the `zstd` algorithm is supported. Include an example MigrationPolicy. - -Use the release notes entries as the starting point. Ask the feature authors to confirm limitations, and phrase unconfirmed details as questions. +Three v1.9 features appear only in `docs/release_notes.md`, so users cannot find +them in the feature pages. Add a section for each: + +- **`CrossArchitectureVirtualization` feature gate** (Alpha): Add a section to a + Compute page or to `docs/cluster_admin/activating_feature_gates.md`. Explain + that VMs can run on nodes with a different architecture through QEMU software + emulation (TCG), that the scheduler prefers native-architecture nodes and + falls back to emulation, and how to enable the gate. +- **Masquerade `PortRanges`** (Alpha, guarded by the `PortRangesSpec` feature + gate): Add a section to `docs/network/interfaces_and_networks.md` that shows + how to define port ranges on a masquerade interface, with an example and the + gate to enable. +- **MigrationPolicy compression**: Add a section to + `docs/cluster_admin/migration_policies.md` that explains the + `.spec.experimental.compression` field. It compresses the live migration data + stream, and only the `zstd` algorithm is supported. Include an example + MigrationPolicy. + +Use the release notes entries as the starting point. Ask the feature authors to +confirm limitations, and phrase unconfirmed details as questions. ## What you expected -Each feature is documented next to related content with an example manifest, the required feature gate, and its maturity stage. +Each feature is documented next to related content with an example manifest, the +required feature gate, and its maturity stage. ## URL @@ -24,10 +39,16 @@ Each feature is documented next to related content with an example manifest, the - https://kubevirt.io/user-guide/network/interfaces_and_networks/ - https://kubevirt.io/user-guide/cluster_admin/migration_policies/ - https://kubevirt.io/user-guide/cluster_admin/activating_feature_gates/ -- `docs/network/interfaces_and_networks.md`, `docs/cluster_admin/migration_policies.md`, `docs/cluster_admin/activating_feature_gates.md` +- `docs/network/interfaces_and_networks.md`, + `docs/cluster_admin/migration_policies.md`, + `docs/cluster_admin/activating_feature_gates.md` ## Additional context -The feature-gate table in #9015 should list these gates. The Backup API is covered separately in #9012. +The feature-gate table in #9015 should list these gates. The Backup API is +covered separately in #9012. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md b/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md index 90edf227..997a88df 100644 --- a/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md +++ b/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md @@ -6,19 +6,30 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The `virtctl` page covers only downloading and installing the client. No page lists the subcommands, so users must read many feature pages, or run `virtctl --help`, to learn what the tool does. +The `virtctl` page covers only downloading and installing the client. No page +lists the subcommands, so users must read many feature pages, or run +`virtctl --help`, to learn what the tool does. -Create a `docs/user_workloads/virtctl_reference.md` page, or expand the existing `virtctl` page beyond installation, and add it to `docs/user_workloads/.nav.yml`. The page lists each `virtctl` subcommand in a table with: +Create a `docs/user_workloads/virtctl_reference.md` page, or expand the existing +`virtctl` page beyond installation, and add it to +`docs/user_workloads/.nav.yml`. The page lists each `virtctl` subcommand in a +table with: - The command name, in code formatting. - A one-line description. -- A link to the feature page that explains it in context, for example `virtctl console` to Accessing Virtual Machines and `virtctl vmexport` to the Export API page. +- A link to the feature page that explains it in context, for example + `virtctl console` to Accessing Virtual Machines and `virtctl vmexport` to the + Export API page. -Group the commands by task, such as VM lifecycle, access, storage, and diagnostics. Generate the command list from `virtctl --help` of a current release, and ask the maintainers whether the list can be produced automatically from the `kubevirt/kubevirt` source to avoid drift. +Group the commands by task, such as VM lifecycle, access, storage, and +diagnostics. Generate the command list from `virtctl --help` of a current +release, and ask the maintainers whether the list can be produced automatically +from the `kubevirt/kubevirt` source to avoid drift. ## What you expected -A reader finds every `virtctl` subcommand in one table and can follow a link to learn how to use it. +A reader finds every `virtctl` subcommand in one table and can follow a link to +learn how to use it. ## URL @@ -27,6 +38,10 @@ A reader finds every `virtctl` subcommand in one table and can follow a link to ## Additional context -If #9005 renames the `virtctl` page to "Installing virtctl", keep installation and reference content on separate pages and link them to each other. +If #9005 renames the `virtctl` page to "Installing virtctl", keep installation +and reference content on separate pages and link them to each other. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md b/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md index dad128c0..3de45a4c 100644 --- a/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md +++ b/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md @@ -6,20 +6,29 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Activating and Deactivating Feature Gates page explains the Alpha, Beta, and GA stages but does not list the gates themselves. Readers must search the guide and the release notes to learn which gates exist, their maturity, and where they are documented. +The Activating and Deactivating Feature Gates page explains the Alpha, Beta, and +GA stages but does not list the gates themselves. Readers must search the guide +and the release notes to learn which gates exist, their maturity, and where they +are documented. -Add a table to `docs/cluster_admin/activating_feature_gates.md` with one row per feature gate and these columns: +Add a table to `docs/cluster_admin/activating_feature_gates.md` with one row per +feature gate and these columns: - Gate name, in code formatting. - Stage: Alpha, Beta, GA, or Deprecated. - Version in which the gate was introduced or graduated. - Link to the page that documents the feature. -Source the rows from the `kubevirt/kubevirt` feature gate definitions and the release notes. Ask the maintainers whether this table can be generated from the `kubevirt/kubevirt` source to avoid drift, and if so, describe the generation step in the page's source comments or in `CONTRIBUTING.md`. If gates have no documentation, leave the link empty and note it in the pull request. +Source the rows from the `kubevirt/kubevirt` feature gate definitions and the +release notes. Ask the maintainers whether this table can be generated from the +`kubevirt/kubevirt` source to avoid drift, and if so, describe the generation +step in the page's source comments or in `CONTRIBUTING.md`. If gates have no +documentation, leave the link empty and note it in the pull request. ## What you expected -A reader finds every feature gate, its stage, and its documentation in one table, and the table has a defined way to stay current. +A reader finds every feature gate, its stage, and its documentation in one +table, and the table has a defined way to stay current. ## URL @@ -28,6 +37,12 @@ A reader finds every feature gate, its stage, and its documentation in one table ## Additional context -Include the gates documented in #9013 (`CrossArchitectureVirtualization` and `PortRangesSpec`). The Arm64 page `docs/cluster_admin/feature_gate_status_on_Arm64.md` is a separate topic; link to it rather than merging it. +Include the gates documented in #9013 (`CrossArchitectureVirtualization` and +`PortRangesSpec`). The Arm64 page +`docs/cluster_admin/feature_gate_status_on_Arm64.md` is a separate topic; link +to it rather than merging it. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md b/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md index e2b29270..360ffa06 100644 --- a/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md +++ b/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md @@ -6,30 +6,47 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Troubleshooting content is scattered. The Virtualization Debugging section targets developers (`strace`, `gdb`, `virsh`), while user-level notes sit inside Accessing Virtual Machines and Memory Dump. A user whose VirtualMachineInstance does not start has no obvious place to look. +Troubleshooting content is scattered. The Virtualization Debugging section +targets developers (`strace`, `gdb`, `virsh`), while user-level notes sit inside +Accessing Virtual Machines and Memory Dump. A user whose VirtualMachineInstance +does not start has no obvious place to look. -Add `docs/user_workloads/troubleshooting.md` and list it in `docs/user_workloads/.nav.yml`. Structure the page by symptom. For each symptom, list likely causes and link to the fix: +Add `docs/user_workloads/troubleshooting.md` and list it in +`docs/user_workloads/.nav.yml`. Structure the page by symptom. For each symptom, +list likely causes and link to the fix: - A VirtualMachineInstance stuck in `Scheduling` or `Pending`. - A failed live migration. - Console or VNC connection errors. - Missing `qemu-guest-agent` data. -Consolidate the troubleshooting notes now embedded in `docs/user_workloads/accessing_virtual_machines.md` and `docs/compute/memory_dump.md` into the new page, or link to them from it. Link the new page from the Virtualization Debugging introduction as the first stop before the developer-level guides. Confirm causes and fixes with maintainers, and phrase uncertain items as questions. +Consolidate the troubleshooting notes now embedded in +`docs/user_workloads/accessing_virtual_machines.md` and +`docs/compute/memory_dump.md` into the new page, or link to them from it. Link +the new page from the Virtualization Debugging introduction as the first stop +before the developer-level guides. Confirm causes and fixes with maintainers, +and phrase uncertain items as questions. ## What you expected -A user who sees a failure finds the symptom on one page, learns the likely causes, and follows a link to the fix. +A user who sees a failure finds the symptom on one page, learns the likely +causes, and follows a link to the fix. ## URL - https://kubevirt.io/user-guide/user_workloads/accessing_virtual_machines/ - https://kubevirt.io/user-guide/compute/memory_dump/ - https://kubevirt.io/user-guide/debug_virt_stack/debug/ -- `docs/user_workloads/accessing_virtual_machines.md`, `docs/compute/memory_dump.md`, `docs/debug_virt_stack/debug.md` +- `docs/user_workloads/accessing_virtual_machines.md`, + `docs/compute/memory_dump.md`, `docs/debug_virt_stack/debug.md` ## Additional context -Start with the four symptoms above and leave room to grow. Ask maintainers for the most frequent support questions from the Slack channel and issue tracker to prioritize further entries. +Start with the four symptoms above and leave room to grow. Ask maintainers for +the most frequent support questions from the Slack channel and issue tracker to +prioritize further entries. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md b/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md index 8c743d41..8c3d91af 100644 --- a/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md +++ b/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md @@ -6,19 +6,33 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Feature pages mark their maturity with a `**FEATURE STATE:**` line, but the format varies. Some pages state a version only (`KubeVirt v0.43`), some add a stage (`v1.9.0: Beta`, `(Alpha)`, `(experimental support)`), and some leave the value empty or use a heading (`### **FEATURE STATE:**`). The guide publishes only one version, so readers rely on these markers to know whether a feature exists in their release and how mature it is. - -Define one admonition format that states the version introduced and the current stage (Alpha, Beta, GA, or Deprecated), and apply it to every page that has a feature-state marker: - -- `docs/compute/live_migration.md`, `numa.md`, `persistent_tpm_and_uefi_state.md`, and `dra_gpu.md` +Feature pages mark their maturity with a `**FEATURE STATE:**` line, but the +format varies. Some pages state a version only (`KubeVirt v0.43`), some add a +stage (`v1.9.0: Beta`, `(Alpha)`, `(experimental support)`), and some leave the +value empty or use a heading (`### **FEATURE STATE:**`). The guide publishes +only one version, so readers rely on these markers to know whether a feature +exists in their release and how mature it is. + +Define one admonition format that states the version introduced and the current +stage (Alpha, Beta, GA, or Deprecated), and apply it to every page that has a +feature-state marker: + +- `docs/compute/live_migration.md`, `numa.md`, + `persistent_tpm_and_uefi_state.md`, and `dra_gpu.md` - `docs/cluster_admin/confidential_computing.md` -- `docs/user_workloads/vm_templates.md`, `deploy_common_instancetypes.md`, `presets.md`, and `instancetypes.md` +- `docs/user_workloads/vm_templates.md`, `deploy_common_instancetypes.md`, + `presets.md`, and `instancetypes.md` -Use the existing `admonition` extension, for example `!!! info "Feature state"` followed by a line such as `Introduced in KubeVirt v1.9 (Alpha)`. Fill in the empty markers using the release notes. Ask the maintainers for the current stage of any feature you cannot confirm. Add the chosen format, with an example, to `CONTRIBUTING.md` so new pages follow it. +Use the existing `admonition` extension, for example `!!! info "Feature state"` +followed by a line such as `Introduced in KubeVirt v1.9 (Alpha)`. Fill in the +empty markers using the release notes. Ask the maintainers for the current stage +of any feature you cannot confirm. Add the chosen format, with an example, to +`CONTRIBUTING.md` so new pages follow it. ## What you expected -Every feature page shows the same admonition with the introduced version and stage, and contributors know how to write it for new pages. +Every feature page shows the same admonition with the introduced version and +stage, and contributors know how to write it for new pages. ## URL @@ -31,6 +45,10 @@ Every feature page shows the same admonition with the introduced version and sta ## Additional context -The feature-gate table in #9015 reports the same stages; keep the two consistent. Contributor guide additions are tracked in #9020. +The feature-gate table in #9015 reports the same stages; keep the two +consistent. Contributor guide additions are tracked in #9020. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9018-document-versioning-model.md b/analyses/2026/kubevirt/issues/9018-document-versioning-model.md index 3fe4ba7a..dc4fb828 100644 --- a/analyses/2026/kubevirt/issues/9018-document-versioning-model.md +++ b/analyses/2026/kubevirt/issues/9018-document-versioning-model.md @@ -1,22 +1,40 @@ --- -title: Document the content versioning model, release-notes process, and localization #9018 +title: Document the content versioning model, release-notes process, and + localization #9018 labels: [high, help wanted] repo: https://github.com/kubevirt/user-guide/issues --- ## Description -The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but no page explains how they work. Contributors cannot tell which branch is published or whether a change on `main` needs a cherry-pick. The release notes are regenerated with `update_changelog.sh`, but nothing records who runs it or when. The project also has no stated position on translations. - -Add three sections to `CONTRIBUTING.md`, and summarize the first on the Contributing page (`docs/contributing.md`): - -1. **Content versioning.** State what the `release-vX.Y-stable` and `release-vX.Y-devel` branches are for, when they are cut relative to a KubeVirt release, which branch is published, and how a contributor decides whether a change needs a cherry-pick. The `-devel` branches exist for 1.7 and 1.8 but not 1.9; ask the maintainers to confirm the intended workflow before you write it. -2. **Release notes.** Describe when `update_changelog.sh` runs, who runs it, and how the result is reviewed. -3. **Localization.** Record the current position: English only, translations not accepted, or translations welcome through a stated process. Ask the maintainers which applies. If they expect translations within a few releases, open a follow-up issue to move content to `docs/en/` and configure the `mkdocs-static-i18n` plugin. +The repository has `release-vX.Y-stable` and `release-vX.Y-devel` branches, but +no page explains how they work. Contributors cannot tell which branch is +published or whether a change on `main` needs a cherry-pick. The release notes +are regenerated with `update_changelog.sh`, but nothing records who runs it or +when. The project also has no stated position on translations. + +Add three sections to `CONTRIBUTING.md`, and summarize the first on the +Contributing page (`docs/contributing.md`): + +1. **Content versioning.** State what the `release-vX.Y-stable` and + `release-vX.Y-devel` branches are for, when they are cut relative to a + KubeVirt release, which branch is published, and how a contributor decides + whether a change needs a cherry-pick. The `-devel` branches exist for 1.7 and + 1.8 but not 1.9; ask the maintainers to confirm the intended workflow before + you write it. +2. **Release notes.** Describe when `update_changelog.sh` runs, who runs it, and + how the result is reviewed. +3. **Localization.** Record the current position: English only, translations not + accepted, or translations welcome through a stated process. Ask the + maintainers which applies. If they expect translations within a few releases, + open a follow-up issue to move content to `docs/en/` and configure the + `mkdocs-static-i18n` plugin. ## What you expected -A contributor reads `CONTRIBUTING.md` and knows which branch to target, whether to cherry-pick, how release notes are produced, and whether translations are accepted. +A contributor reads `CONTRIBUTING.md` and knows which branch to target, whether +to cherry-pick, how release notes are produced, and whether translations are +accepted. ## URL @@ -26,6 +44,11 @@ A contributor reads `CONTRIBUTING.md` and knows which branch to target, whether ## Additional context -The maintainers must confirm the branch workflow first. Coordinate with #9019, which publishes versioned documentation, and #9020, which expands the contributor guide. +The maintainers must confirm the branch workflow first. Coordinate with #9019, +which publishes versioned documentation, and #9020, which expands the +contributor guide. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md index f6b6ce36..01fec5ff 100644 --- a/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md +++ b/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md @@ -6,24 +6,33 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide publishes a single version of the documentation. A reader running an older KubeVirt release cannot find content for that release, and features such as v1.9 Beta-by-default behavior apply only to newer versions. Release branches already exist in the repository, but the site does not expose them. +The user guide publishes a single version of the documentation. A reader running +an older KubeVirt release cannot find content for that release, and features +such as v1.9 Beta-by-default behavior apply only to newer versions. Release +branches already exist in the repository, but the site does not expose them. Publish versioned documentation with a version selector. Choose one approach: -- Use `mike` with `extra.version.provider: mike` in `mkdocs.yml`, which adds the theme's version selector. +- Use `mike` with `extra.version.provider: mike` in `mkdocs.yml`, which adds the + theme's version selector. - Build each release branch and publish it under a `/vX.Y/` path. The result: -- Publishes at least the supported N, N-1, and N-2 minor versions alongside `latest`. +- Publishes at least the supported N, N-1, and N-2 minor versions alongside + `latest`. - Shows a version selector in the header on every page. - Redirects the unversioned URL to `latest`, so existing links keep working. -Write a short design note in the pull request that compares the two approaches and explains how the publishing job in the project's CI changes. Ask the maintainers who owns the publishing pipeline and which versions are supported. +Write a short design note in the pull request that compares the two approaches +and explains how the publishing job in the project's CI changes. Ask the +maintainers who owns the publishing pipeline and which versions are supported. ## What you expected -A reader selects their KubeVirt version from the header and sees the documentation for that release. Existing links to the unversioned site still resolve. +A reader selects their KubeVirt version from the header and sees the +documentation for that release. Existing links to the unversioned site still +resolve. ## URL @@ -32,6 +41,13 @@ A reader selects their KubeVirt version from the header and sees the documentati ## Additional context -Depends on #9018, which documents the branch model that the versioned builds rely on. Until this issue is complete, the feature-state admonitions from #9017 stand in for versioning. The user guide is published beneath kubevirt.io, so confirm with the website maintainers that the `/vX.Y/` paths fit the website's routing (see #9045). +Depends on #9018, which documents the branch model that the versioned builds +rely on. Until this issue is complete, the feature-state admonitions from #9017 +stand in for versioning. The user guide is published beneath kubevirt.io, so +confirm with the website maintainers that the `/vX.Y/` paths fit the website's +routing (see #9045). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md b/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md index f5d7edd5..4fe44be0 100644 --- a/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md +++ b/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md @@ -6,21 +6,32 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -`CONTRIBUTING.md` is a pointer to the Contributing page on the published site. The steps for building the guide live in `README.md`, and nothing in the repository describes the full path from an idea to a merged change. Contributors must guess the review process. +`CONTRIBUTING.md` is a pointer to the Contributing page on the published site. +The steps for building the guide live in `README.md`, and nothing in the +repository describes the full path from an idea to a merged change. Contributors +must guess the review process. -Expand `CONTRIBUTING.md` into a documentation contributor guide that covers the full lifecycle: +Expand `CONTRIBUTING.md` into a documentation contributor guide that covers the +full lifecycle: - How to propose a change: open an issue first or send a pull request directly. -- How to build and test locally. Move the build steps from `README.md` into this guide, and leave a link in `README.md`. -- What happens after you open a pull request: labels, the `/lgtm` and `/approve` commands, and the expected turnaround time. Ask the maintainers for the typical turnaround. +- How to build and test locally. Move the build steps from `README.md` into this + guide, and leave a link in `README.md`. +- What happens after you open a pull request: labels, the `/lgtm` and `/approve` + commands, and the expected turnaround time. Ask the maintainers for the + typical turnaround. - When to add a redirect to `mkdocs.yml` and when to update `.nav.yml`. - When a change needs a cherry-pick to a `release-vX.Y-stable` branch. -Use the Thanos "How to contribute to docs" page as a model for structure and tone. Keep the Contributing page in `docs/contributing.md` as a short summary that links to the full guide. +Use the Thanos "How to contribute to docs" page as a model for structure and +tone. Keep the Contributing page in `docs/contributing.md` as a short summary +that links to the full guide. ## What you expected -A first-time contributor can go from a documentation idea to a merged pull request using only `CONTRIBUTING.md`, including how to build locally and what reviewers do. +A first-time contributor can go from a documentation idea to a merged pull +request using only `CONTRIBUTING.md`, including how to build locally and what +reviewers do. ## URL @@ -29,6 +40,11 @@ A first-time contributor can go from a documentation idea to a merged pull reque ## Additional context -The cherry-pick guidance depends on the branch model written in #9018, and the feature-state format from #9017 belongs in this guide too. Write the sections in a consistent order to avoid conflicts between the pull requests. +The cherry-pick guidance depends on the branch model written in #9018, and the +feature-state format from #9017 belongs in this guide too. Write the sections in +a consistent order to avoid conflicts between the pull requests. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9021-add-style-guide.md b/analyses/2026/kubevirt/issues/9021-add-style-guide.md index b1bc3ad5..2cb80154 100644 --- a/analyses/2026/kubevirt/issues/9021-add-style-guide.md +++ b/analyses/2026/kubevirt/issues/9021-add-style-guide.md @@ -6,31 +6,49 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide has no written style guide. Contributors infer page structure, admonition use, code block format, and naming from existing pages, so pages drift apart and reviewers repeat the same feedback in every pull request. +The user guide has no written style guide. Contributors infer page structure, +admonition use, code block format, and naming from existing pages, so pages +drift apart and reviewers repeat the same feedback in every pull request. -Add a short style guide, for example `docs/style_guide.md`, and add it to the Contributing section in `docs/.nav.yml`. Cover these topics, each with a one- or two-line rule and a short example: +Add a short style guide, for example `docs/style_guide.md`, and add it to the +Contributing section in `docs/.nav.yml`. Cover these topics, each with a one- or +two-line rule and a short example: -- Page structure: title, short concept paragraph, feature-state banner, procedure, related links. +- Page structure: title, short concept paragraph, feature-state banner, + procedure, related links. - The standard feature-state admonition and when to use it. -- Code blocks: fenced blocks with a language tag, and no `$` prompts so readers can copy commands. -- Capitalization of Kubernetes objects, such as VirtualMachine, in UpperCamelCase. +- Code blocks: fenced blocks with a language tag, and no `$` prompts so readers + can copy commands. +- Capitalization of Kubernetes objects, such as VirtualMachine, in + UpperCamelCase. - File naming under `docs/`. -- Minimizing language: avoid "simple", "simply", "easy", "easily", "just", and "obviously", and explain in one line that these words discourage readers who find the step difficult. +- Minimizing language: avoid "simple", "simply", "easy", "easily", "just", and + "obviously", and explain in one line that these words discourage readers who + find the step difficult. Link the style guide from `CONTRIBUTING.md` and from the Contributing page. ## What you expected -A contributor can read one short page and learn how to structure and format a new page, including which words to avoid. Reviewers can point to the style guide instead of repeating the rules. +A contributor can read one short page and learn how to structure and format a +new page, including which words to avoid. Reviewers can point to the style guide +instead of repeating the rules. ## URL -- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- Contributing page: https://kubevirt.io/user-guide/contributing/ + (`docs/contributing.md`) - `CONTRIBUTING.md` in the repository root - `docs/.nav.yml` ## Additional context -Related: #9020 (expand `CONTRIBUTING.md`), #9022 (pull request template checklist), #9027 (reword existing minimizing language), and #9028 (automated language check). Ask the maintainers which feature-state banner wording is the standard so the guide documents the right one. +Related: #9020 (expand `CONTRIBUTING.md`), #9022 (pull request template +checklist), #9027 (reword existing minimizing language), and #9028 (automated +language check). Ask the maintainers which feature-state banner wording is the +standard so the guide documents the right one. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md b/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md index b8841ed3..e50e54cb 100644 --- a/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md +++ b/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md @@ -6,30 +6,43 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide repository has no pull request template, so authors do not see the checks that reviewers expect. Missing `.nav.yml` entries, missing redirects for moved pages, and missing feature-state banners then surface only in review. +The user guide repository has no pull request template, so authors do not see +the checks that reviewers expect. Missing `.nav.yml` entries, missing redirects +for moved pages, and missing feature-state banners then surface only in review. -Add `.github/pull_request_template.md` with a short description prompt and a checklist: +Add `.github/pull_request_template.md` with a short description prompt and a +checklist: - The relevant `.nav.yml` is updated for every new page. - A redirect is added to `mkdocs.yml` for every moved or renamed page. - `make check_spelling` and `make check_links` pass. - The feature-state banner is present on feature pages. -- The related kubevirt/kubevirt pull request or VEP (KubeVirt Enhancement Proposal) is linked. +- The related kubevirt/kubevirt pull request or VEP (KubeVirt Enhancement + Proposal) is linked. -Keep the template under about 20 lines so authors actually read it. Check whether the Prow `release-note` block that kubevirt repositories use should also appear in the template. Ask the maintainers to confirm. +Keep the template under about 20 lines so authors actually read it. Check +whether the Prow `release-note` block that kubevirt repositories use should also +appear in the template. Ask the maintainers to confirm. ## What you expected -Every new pull request opens with the checklist pre-filled, and authors confirm each item before requesting review. +Every new pull request opens with the checklist pre-filled, and authors confirm +each item before requesting review. ## URL - Repository: https://github.com/kubevirt/user-guide - New file: `.github/pull_request_template.md` -- Guide pages the checklist refers to: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- Guide pages the checklist refers to: + https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) ## Additional context -Related: #9021 (style guide, which the checklist should link), #9020 (expanded `CONTRIBUTING.md`), and #9037 (first change walkthrough). Make the checklist wording match the commands those pages describe. +Related: #9021 (style guide, which the checklist should link), #9020 (expanded +`CONTRIBUTING.md`), and #9037 (first change walkthrough). Make the checklist +wording match the commands those pages describe. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index ef2561c2..0e979550 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -6,29 +6,45 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -All documentation reviews in the user guide route through the root `OWNERS` file. Pull requests on networking, storage, or compute pages therefore wait for general approvers instead of subject-matter experts, which adds to the open pull request backlog. +All documentation reviews in the user guide route through the root `OWNERS` +file. Pull requests on networking, storage, or compute pages therefore wait for +general approvers instead of subject-matter experts, which adds to the open pull +request backlog. -Add `OWNERS` files in the topic directories and reference the existing aliases in `OWNERS_ALIASES`: +Add `OWNERS` files in the topic directories and reference the existing aliases +in `OWNERS_ALIASES`: - `docs/network/OWNERS` with the `sig-network-*` aliases. - `docs/storage/OWNERS` with the `sig-storage-*` aliases. - `docs/compute/OWNERS` with the `sig-compute-*` aliases. -Keep the root `OWNERS` approvers for site-wide changes such as `mkdocs.yml` and `.nav.yml`. Use `reviewers` for the SIG aliases, and decide whether they should also be `approvers`. Verify the alias names against `OWNERS_ALIASES` before writing the files. If an alias does not exist, ask the maintainers whether to add it. +Keep the root `OWNERS` approvers for site-wide changes such as `mkdocs.yml` and +`.nav.yml`. Use `reviewers` for the SIG aliases, and decide whether they should +also be `approvers`. Verify the alias names against `OWNERS_ALIASES` before +writing the files. If an alias does not exist, ask the maintainers whether to +add it. ## What you expected -A pull request that changes only `docs/network/` requests review from networking experts, while root approvers still approve site-wide changes. +A pull request that changes only `docs/network/` requests review from networking +experts, while root approvers still approve site-wide changes. ## URL - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root - New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` -- Guide sections: https://kubevirt.io/user-guide/network/, https://kubevirt.io/user-guide/storage/, https://kubevirt.io/user-guide/compute/ +- Guide sections: https://kubevirt.io/user-guide/network/, + https://kubevirt.io/user-guide/storage/, + https://kubevirt.io/user-guide/compute/ ## Additional context -Related: #9024 (a documentation reviewer role or SIG home) and #9026 (`MAINTAINERS.md` and emeritus review of `OWNERS_ALIASES`). Ask the maintainers whether SIG members want to receive documentation review requests. +Related: #9024 (a documentation reviewer role or SIG home) and #9026 +(`MAINTAINERS.md` and emeritus review of `OWNERS_ALIASES`). Ask the maintainers +whether SIG members want to receive documentation review requests. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md b/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md index 2fe1148a..e078c5c2 100644 --- a/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md +++ b/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md @@ -6,17 +6,27 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Documentation has no clear organizational home. The `sig/documentation` entry in the community `sig-list.md` lacks chairs, a meeting cadence or async channel, and a charter. Newcomers cannot tell where to volunteer, and maintainers have no succession path. The SIG Storage charter has a "Meeting Mechanics" section, but it is unclear whether every SIG charter does. +Documentation has no clear organizational home. The `sig/documentation` entry in +the community `sig-list.md` lacks chairs, a meeting cadence or async channel, +and a charter. Newcomers cannot tell where to volunteer, and maintainers have no +succession path. The SIG Storage charter has a "Meeting Mechanics" section, but +it is unclear whether every SIG charter does. Open a pull request against kubevirt/community that does the following: -- Populates the `sig/documentation` entry in `sig-list.md` with chairs, a meeting cadence or an async channel, and a charter covering both the user guide and the website. -- Records each SIG's meeting cadence and Slack channel in `sigs.yaml`, so the generated SIG list shows how to join every group. -- Adds a "Meeting Mechanics" section to each SIG charter that lacks one, modeled on the SIG Storage charter. +- Populates the `sig/documentation` entry in `sig-list.md` with chairs, a + meeting cadence or an async channel, and a charter covering both the user + guide and the website. +- Records each SIG's meeting cadence and Slack channel in `sigs.yaml`, so the + generated SIG list shows how to join every group. +- Adds a "Meeting Mechanics" section to each SIG charter that lacks one, modeled + on the SIG Storage charter. ## What you expected -A newcomer can find the documentation group in the SIG list, see who leads it and when or where it meets, and find the same details for every other SIG in one generated list. +A newcomer can find the documentation group in the SIG list, see who leads it +and when or where it meets, and find the same details for every other SIG in one +generated list. ## URL @@ -28,10 +38,16 @@ A newcomer can find the documentation group in the SIG list, see who leads it an Questions for the maintainers: -- Should documentation become its own SIG, or a working group under an existing SIG? +- Should documentation become its own SIG, or a working group under an existing + SIG? - Who volunteers as chair, and does the group meet or work asynchronously? - Does every SIG charter already contain "Meeting Mechanics"? -Related: #9023 (per-directory `OWNERS` files), #9026 (`MAINTAINERS.md` and maintainer ladder), and #9039 (triage cadence, which could run in the group's meeting). +Related: #9023 (per-directory `OWNERS` files), #9026 (`MAINTAINERS.md` and +maintainer ladder), and #9039 (triage cadence, which could run in the group's +meeting). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9025-triage-open-prs.md b/analyses/2026/kubevirt/issues/9025-triage-open-prs.md index 0c1e5a1d..ef50439d 100644 --- a/analyses/2026/kubevirt/issues/9025-triage-open-prs.md +++ b/analyses/2026/kubevirt/issues/9025-triage-open-prs.md @@ -6,28 +6,43 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide repository has twelve open pull requests, some of them old. Contributors who open a pull request cannot tell how long review should take or what happens when a pull request goes quiet. +The user guide repository has twelve open pull requests, some of them old. +Contributors who open a pull request cannot tell how long review should take or +what happens when a pull request goes quiet. Do the following: -- Review each open pull request in https://github.com/kubevirt/user-guide/pulls. Merge, request changes, or close each one with a short comment. Start with the oldest. -- Add a "Stale pull requests" subsection to `CONTRIBUTING.md` that states the expected first-response time, when a pull request is marked stale, and when it closes. Align the wording with the Prow lifecycle labels (`lifecycle/stale`, `lifecycle/rotten`) the project already uses. +- Review each open pull request in https://github.com/kubevirt/user-guide/pulls. + Merge, request changes, or close each one with a short comment. Start with the + oldest. +- Add a "Stale pull requests" subsection to `CONTRIBUTING.md` that states the + expected first-response time, when a pull request is marked stale, and when it + closes. Align the wording with the Prow lifecycle labels (`lifecycle/stale`, + `lifecycle/rotten`) the project already uses. - Mirror the same text on the Contributing page. -Ask the maintainers to confirm realistic turnaround times before publishing them. +Ask the maintainers to confirm realistic turnaround times before publishing +them. ## What you expected -No pull request older than the stated policy remains without a decision. Contributors read how long to wait for a review and what happens to inactive pull requests. +No pull request older than the stated policy remains without a decision. +Contributors read how long to wait for a review and what happens to inactive +pull requests. ## URL - Open pull requests: https://github.com/kubevirt/user-guide/pulls - `CONTRIBUTING.md` in the repository root -- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- Contributing page: https://kubevirt.io/user-guide/contributing/ + (`docs/contributing.md`) ## Additional context -Related: #9020 (expanded `CONTRIBUTING.md`, which should hold the policy), #9023 (`OWNERS` files to share review load), and #9024 (documentation reviewer role). +Related: #9020 (expanded `CONTRIBUTING.md`, which should hold the policy), #9023 +(`OWNERS` files to share review load), and #9024 (documentation reviewer role). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md index e9424da4..940bd7b8 100644 --- a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -6,28 +6,47 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide does not say who its approvers are, who owns the release-notes script, or how a contributor becomes a reviewer or approver. `OWNERS_ALIASES` may also list people who are no longer active. The website repository already records dated emeritus entries. +The user guide does not say who its approvers are, who owns the release-notes +script, or how a contributor becomes a reviewer or approver. `OWNERS_ALIASES` +may also list people who are no longer active. The website repository already +records dated emeritus entries. Make these changes in the user guide repository: -- Add `MAINTAINERS.md` that names the user guide approvers, names the person or group responsible for the release-notes script, and says how to reach them. Alternatively, add a "Maintainers" section to the Contributing page. Model it on the NATS site `MAINTAINERS` file. -- Add a "Becoming a reviewer or approver" section to the README that describes the path from contributor to reviewer to approver, for example a number of merged documentation pull requests plus a nomination. Mirror the process in kubevirt/community for code SIGs. -- Review `OWNERS_ALIASES`, and move inactive people to dated emeritus entries as the website repository does. +- Add `MAINTAINERS.md` that names the user guide approvers, names the person or + group responsible for the release-notes script, and says how to reach them. + Alternatively, add a "Maintainers" section to the Contributing page. Model it + on the NATS site `MAINTAINERS` file. +- Add a "Becoming a reviewer or approver" section to the README that describes + the path from contributor to reviewer to approver, for example a number of + merged documentation pull requests plus a nomination. Mirror the process in + kubevirt/community for code SIGs. +- Review `OWNERS_ALIASES`, and move inactive people to dated emeritus entries as + the website repository does. ## What you expected -A reader can find the current approvers and a contact, can see how to grow into the role, and can trust that the approver list reflects active people. +A reader can find the current approvers and a contact, can see how to grow into +the role, and can trust that the approver list reflects active people. ## URL -- Repository: https://github.com/kubevirt/user-guide (`OWNERS`, `OWNERS_ALIASES`, README) -- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) -- kubevirt/community membership policy: https://github.com/kubevirt/community/blob/main/membership_policy.md +- Repository: https://github.com/kubevirt/user-guide (`OWNERS`, + `OWNERS_ALIASES`, README) +- Contributing page: https://kubevirt.io/user-guide/contributing/ + (`docs/contributing.md`) +- kubevirt/community membership policy: + https://github.com/kubevirt/community/blob/main/membership_policy.md ## Additional context -Questions for the maintainers: Who should be listed as the release-notes script owner? How many merged pull requests should the ladder require? +Questions for the maintainers: Who should be listed as the release-notes script +owner? How many merged pull requests should the ladder require? -Related: #9023 (`OWNERS` files), #9024 (SIG home), and #9034 (the Contributing page should link `MAINTAINERS.md`). +Related: #9023 (`OWNERS` files), #9024 (SIG home), and #9034 (the Contributing +page should link `MAINTAINERS.md`). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md b/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md index 20e32baa..c65098b5 100644 --- a/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md +++ b/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md @@ -6,7 +6,11 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Many pages use minimizing words such as "simply", "just", "of course", "obviously", "easy", and "easily". These words add nothing and can discourage readers who find a step difficult. The Live Migration page also says migrations "can be easily cancelled" without saying how, and uses "abort" where readers expect "cancel". +Many pages use minimizing words such as "simply", "just", "of course", +"obviously", "easy", and "easily". These words add nothing and can discourage +readers who find a step difficult. The Live Migration page also says migrations +"can be easily cancelled" without saying how, and uses "abort" where readers +expect "cancel". Edit the pages with the most occurrences first: @@ -16,13 +20,17 @@ Edit the pages with the most occurrences first: - `docs/compute/vsock.md` - `docs/storage/disks_and_volumes.md` -Delete the minimizing word where the sentence works without it. Replace "easy" or "easily" with what the step requires. For example, change "can be easily cancelled" to "can be cancelled by deleting the migration object". +Delete the minimizing word where the sentence works without it. Replace "easy" +or "easily" with what the step requires. For example, change "can be easily +cancelled" to "can be cancelled by deleting the migration object". -On the Live Migration page, prefer "cancel" in prose. Keep field names such as `Abort Requested` and `Abort Status` exactly as `kubectl` prints them. +On the Live Migration page, prefer "cancel" in prose. Keep field names such as +`Abort Requested` and `Abort Status` exactly as `kubectl` prints them. ## What you expected -The listed pages contain no minimizing words, and the Live Migration page uses "cancel" consistently in prose while still showing the real field names. +The listed pages contain no minimizing words, and the Live Migration page uses +"cancel" consistently in prose while still showing the real field names. ## URL @@ -33,8 +41,14 @@ The listed pages contain no minimizing words, and the Live Migration page uses " ## Additional context -Question for the API maintainers: Are the `Abort Requested` and `Abort Status` fields in the VirtualMachineInstanceMigration status candidates for a "cancel" alias in a future API version? +Question for the API maintainers: Are the `Abort Requested` and `Abort Status` +fields in the VirtualMachineInstanceMigration status candidates for a "cancel" +alias in a future API version? -Related: #9021 (style guide rule on minimizing language) and #9028 (automated check to prevent regressions). +Related: #9021 (style guide rule on minimizing language) and #9028 (automated +check to prevent regressions). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md b/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md index 256191b3..9c5ace87 100644 --- a/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md +++ b/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md @@ -6,27 +6,45 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The guide's pull request checks cover spelling (`make check_spelling`) and links, but nothing flags minimizing language or accessibility regressions such as low contrast. Both problems return unless a check catches them in the pull request. +The guide's pull request checks cover spelling (`make check_spelling`) and +links, but nothing flags minimizing language or accessibility regressions such +as low contrast. Both problems return unless a check catches them in the pull +request. Add two checks to the `Makefile` and to the Prow pre-submit job: -- A language check. Use Vale with the `write-good` style, or a grep-based target that runs next to `make check_spelling`. Flag "simple", "simply", "easy", "easily", "just", and "obviously". Start in warning mode if existing pages still contain matches. -- An accessibility check. Run `pa11y-ci` or Lighthouse against the built site for a sample of pages, for example the home page, Live Migration, and one storage page. +- A language check. Use Vale with the `write-good` style, or a grep-based target + that runs next to `make check_spelling`. Flag "simple", "simply", "easy", + "easily", "just", and "obviously". Start in warning mode if existing pages + still contain matches. +- An accessibility check. Run `pa11y-ci` or Lighthouse against the built site + for a sample of pages, for example the home page, Live Migration, and one + storage page. -Document both targets in the README and on the Contributing page. Prow job configuration lives in kubevirt/project-infra, so list the change needed there in this issue. +Document both targets in the README and on the Contributing page. Prow job +configuration lives in kubevirt/project-infra, so list the change needed there +in this issue. ## What you expected -A pull request that introduces minimizing language or a contrast failure shows a failing or warning check before review. +A pull request that introduces minimizing language or a contrast failure shows a +failing or warning check before review. ## URL - `Makefile` in https://github.com/kubevirt/user-guide - Prow configuration: https://github.com/kubevirt/project-infra -- Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) +- Contributing page: https://kubevirt.io/user-guide/contributing/ + (`docs/contributing.md`) ## Additional context -Depends on #9027 (existing minimizing language must be fixed before the check can fail builds) and relates to #9048 (contrast fixes) and #9021 (style guide). Question for the maintainers: Should the Prow job block merges or only report warnings at first? +Depends on #9027 (existing minimizing language must be fixed before the check +can fail builds) and relates to #9048 (contrast fixes) and #9021 (style guide). +Question for the maintainers: Should the Prow job block merges or only report +warnings at first? -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). +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). diff --git a/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md b/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md index 61ff041b..5a12484b 100644 --- a/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md +++ b/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md @@ -8,31 +8,46 @@ repo: https://github.com/kubevirt/user-guide/issues The guide still uses the legacy `master` branch name in several places. -- Fourteen links point to `kubevirt.io/api-reference/master/...`. Replace them with the `/main/` path, or with a versioned path such as `/v1.9.0/` where the page documents a specific release. Find them with `grep -rn "api-reference/master" docs`. The links appear in these files: - - `docs/compute/virtual_hardware.md` - - `docs/storage/disks_and_volumes.md` - - `docs/debug_virt_stack/debug.md` - - `docs/cluster_admin/migration_policies.md` - - `docs/cluster_admin/installation.md` - - `docs/cluster_admin/customize_components.md` - - `docs/network/interfaces_and_networks.md` -- `docs/user_workloads/presets.md` uses `kubevirt.io/nodeName: master` in an example. Replace the value with a neutral name such as `node01`, or remove the example, because the page documents a deprecated feature. -- Links to upstream projects such as libvirt, cri-tools, vhost-md, and kubevirt-ansible may also use a default branch name that those projects have since changed. Prefer tagged or permalink URLs for them so the branch name does not appear in the guide. +- Fourteen links point to `kubevirt.io/api-reference/master/...`. Replace them + with the `/main/` path, or with a versioned path such as `/v1.9.0/` where the + page documents a specific release. Find them with + `grep -rn "api-reference/master" docs`. The links appear in these files: + - `docs/compute/virtual_hardware.md` + - `docs/storage/disks_and_volumes.md` + - `docs/debug_virt_stack/debug.md` + - `docs/cluster_admin/migration_policies.md` + - `docs/cluster_admin/installation.md` + - `docs/cluster_admin/customize_components.md` + - `docs/network/interfaces_and_networks.md` +- `docs/user_workloads/presets.md` uses `kubevirt.io/nodeName: master` in an + example. Replace the value with a neutral name such as `node01`, or remove the + example, because the page documents a deprecated feature. +- Links to upstream projects such as libvirt, cri-tools, vhost-md, and + kubevirt-ansible may also use a default branch name that those projects have + since changed. Prefer tagged or permalink URLs for them so the branch name + does not appear in the guide. Run `make check_links` after the edits. ## What you expected -No link or example in the guide uses `master` as a branch or node name, and all edited links resolve. +No link or example in the guide uses `master` as a branch or node name, and all +edited links resolve. ## URL -- https://kubevirt.io/user-guide/user_workloads/presets/ (`docs/user_workloads/presets.md`) -- https://kubevirt.io/user-guide/cluster_admin/installation/ (`docs/cluster_admin/installation.md`) +- https://kubevirt.io/user-guide/user_workloads/presets/ + (`docs/user_workloads/presets.md`) +- https://kubevirt.io/user-guide/cluster_admin/installation/ + (`docs/cluster_admin/installation.md`) - Other files listed above under `docs/` ## Additional context -Question for the maintainers: Should API reference links track `/main/` or the latest released version? +Question for the maintainers: Should API reference links track `/main/` or the +latest released version? -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). +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). diff --git a/analyses/2026/kubevirt/issues/9030-add-community-page.md b/analyses/2026/kubevirt/issues/9030-add-community-page.md index 45e21020..532892f7 100644 --- a/analyses/2026/kubevirt/issues/9030-add-community-page.md +++ b/analyses/2026/kubevirt/issues/9030-add-community-page.md @@ -6,19 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Community channels appear only in the "Getting help" list on the Welcome page. A reader who stays in the guide can miss the Slack channels, the mailing list, community meetings, and social accounts. +Community channels appear only in the "Getting help" list on the Welcome page. A +reader who stays in the guide can miss the Slack channels, the mailing list, +community meetings, and social accounts. -Add a "Community and communication" page, for example `docs/community.md`, and add it to `docs/.nav.yml`. Include: +Add a "Community and communication" page, for example `docs/community.md`, and +add it to `docs/.nav.yml`. Include: -- Channels, each with a one-line purpose: `#virtualization` on Kubernetes Slack for usage questions, `#kubevirt-dev` for contributor discussion, and the kubevirt-dev mailing list for announcements and longer threads. +- Channels, each with a one-line purpose: `#virtualization` on Kubernetes Slack + for usage questions, `#kubevirt-dev` for contributor discussion, and the + kubevirt-dev mailing list for announcements and longer threads. - Social accounts. -- Community meetings: state the cadence, list the meeting times, and link the public calendar (`kubevirt@cncf.io`) so readers can join without leaving the guide. +- Community meetings: state the cadence, list the meeting times, and link the + public calendar (`kubevirt@cncf.io`) so readers can join without leaving the + guide. -Keep the content consistent with the kubevirt.io Community page. Link to that page for governance, and avoid copying content that will go out of date. +Keep the content consistent with the kubevirt.io Community page. Link to that +page for governance, and avoid copying content that will go out of date. ## What you expected -A reader finds every community channel and how to join a meeting in one guide page, and the information matches the kubevirt.io Community page. +A reader finds every community channel and how to join a meeting in one guide +page, and the information matches the kubevirt.io Community page. ## URL @@ -28,8 +37,15 @@ A reader finds every community channel and how to join a meeting in one guide pa ## Additional context -Question for the maintainers: Which source is authoritative for meeting times, the guide, the Community page, or the shared calendar? Prefer linking the calendar to avoid stale times. +Question for the maintainers: Which source is authoritative for meeting times, +the guide, the Community page, or the shared calendar? Prefer linking the +calendar to avoid stale times. -Related: #9031 (Community and adoption block on the index page), #9032 (footer links), #9035 (where to ask for help), and #9040 (Governance section on the Community page). +Related: #9031 (Community and adoption block on the index page), #9032 (footer +links), #9035 (where to ask for help), and #9040 (Governance section on the +Community 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). +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). diff --git a/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md b/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md index ca43bb98..a103e65f 100644 --- a/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md +++ b/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md @@ -6,19 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Readers of the guide get no pointer to the wider KubeVirt community or to evidence of adoption. The Contributing page invites readers to submit case studies, but does not show them what a case study looks like. +Readers of the guide get no pointer to the wider KubeVirt community or to +evidence of adoption. The Contributing page invites readers to submit case +studies, but does not show them what a case study looks like. Make these changes: -- Add a short "Community and adoption" block to `docs/index.md` with links to the kubevirt.io blog, videos, KubeVirt Summit, the adopters or case-studies page, and Slack. -- Optionally add a top-level "Community" entry to `docs/.nav.yml` that opens the kubevirt.io Community page. -- In `docs/contributing.md`, link to the existing adopters list and case studies next to the invitation to submit one, so contributors can see the format to follow. +- Add a short "Community and adoption" block to `docs/index.md` with links to + the kubevirt.io blog, videos, KubeVirt Summit, the adopters or case-studies + page, and Slack. +- Optionally add a top-level "Community" entry to `docs/.nav.yml` that opens the + kubevirt.io Community page. +- In `docs/contributing.md`, link to the existing adopters list and case studies + next to the invitation to submit one, so contributors can see the format to + follow. Verify each target URL before linking and run `make check_links`. ## What you expected -A reader on the Welcome page finds the blog, videos, Summit, adopters, and Slack in one block. A case-study contributor sees existing examples before writing their own. +A reader on the Welcome page finds the blog, videos, Summit, adopters, and Slack +in one block. A case-study contributor sees existing examples before writing +their own. ## URL @@ -29,6 +38,12 @@ A reader on the Welcome page finds the blog, videos, Summit, adopters, and Slack ## Additional context -Related: #9030 (Community and communication page in the guide, which the "Community" entry could use instead of an external link), #9032 (footer links), and #9034 through #9037 (other changes to the Contributing page; coordinate edits to avoid merge conflicts). +Related: #9030 (Community and communication page in the guide, which the +"Community" entry could use instead of an external link), #9032 (footer links), +and #9034 through #9037 (other changes to the Contributing page; coordinate +edits to avoid merge conflicts). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md b/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md index bc01fcc1..e0ab8e77 100644 --- a/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md +++ b/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md @@ -6,18 +6,26 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The guide's header and footer give no link to the repository, Slack, the mailing list, or the main kubevirt.io site. These links appear only in the "Getting help" list on the Welcome page. `mkdocs.yml` sets neither `repo_url` nor an `extra.social` block. +The guide's header and footer give no link to the repository, Slack, the mailing +list, or the main kubevirt.io site. These links appear only in the "Getting +help" list on the Welcome page. `mkdocs.yml` sets neither `repo_url` nor an +`extra.social` block. Edit `mkdocs.yml`: -- Set `repo_url` to `https://github.com/kubevirt/user-guide`. Also set `repo_name` if the default label is unclear. Check that the Material theme shows the repository link in the header. -- Add an `extra.social` block with icons and links for GitHub, Slack, the mailing list, and `kubevirt.io`. +- Set `repo_url` to `https://github.com/kubevirt/user-guide`. Also set + `repo_name` if the default label is unclear. Check that the Material theme + shows the repository link in the header. +- Add an `extra.social` block with icons and links for GitHub, Slack, the + mailing list, and `kubevirt.io`. -Run `mkdocs serve` locally and confirm the links render on every page, in light and dark mode. +Run `mkdocs serve` locally and confirm the links render on every page, in light +and dark mode. ## What you expected -Every page shows the repository link in the header and the GitHub, Slack, mailing list, and kubevirt.io links in the footer. +Every page shows the repository link in the header and the GitHub, Slack, +mailing list, and kubevirt.io links in the footer. ## URL @@ -26,6 +34,11 @@ Every page shows the repository link in the header and the GitHub, Slack, mailin ## Additional context -Related: #9046 (other user guide footer compliance fixes in `mkdocs.yml`, such as the `copyright` line), #9030 (Community page), and #9047 (website footer). Combine the `mkdocs.yml` edits with #9046 if the same contributor takes both. +Related: #9046 (other user guide footer compliance fixes in `mkdocs.yml`, such +as the `copyright` line), #9030 (Community page), and #9047 (website footer). +Combine the `mkdocs.yml` edits with #9046 if the same contributor takes both. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md b/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md index 3d708e77..b52f88c4 100644 --- a/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md +++ b/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md @@ -8,15 +8,23 @@ repo: https://github.com/kubevirt/user-guide/issues Three small problems affect the guide's branding and repository hygiene. -- **Logo alt text.** The header logo has no useful alternative text, so screen readers cannot name it. Set the alt text to "KubeVirt" by adding `extra.homepage` or a custom `partials/logo.html` override in the theme overrides. -- **Unused legacy assets.** Delete `asciibinder-logo-horizontal.png`, `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. Confirm with `grep -rn` that nothing references them first. -- **Unsupported config key.** Remove the top-level `site_favicon: assets/favicon.ico` key from `mkdocs.yml`. MkDocs ignores it, and the active favicon is already set under `theme.favicon`. +- **Logo alt text.** The header logo has no useful alternative text, so screen + readers cannot name it. Set the alt text to "KubeVirt" by adding + `extra.homepage` or a custom `partials/logo.html` override in the theme + overrides. +- **Unused legacy assets.** Delete `asciibinder-logo-horizontal.png`, + `asciibinder_web_logo.svg`, and `book_pages_bg.jpg` from `docs/assets`. + Confirm with `grep -rn` that nothing references them first. +- **Unsupported config key.** Remove the top-level + `site_favicon: assets/favicon.ico` key from `mkdocs.yml`. MkDocs ignores it, + and the active favicon is already set under `theme.favicon`. Build the site and confirm the logo, favicon, and pages still render. ## What you expected -The header logo reads as "KubeVirt" to a screen reader, `docs/assets` contains only current brand assets, and `mkdocs.yml` has no ignored keys. +The header logo reads as "KubeVirt" to a screen reader, `docs/assets` contains +only current brand assets, and `mkdocs.yml` has no ignored keys. ## URL @@ -25,6 +33,11 @@ The header logo reads as "KubeVirt" to a screen reader, `docs/assets` contains o ## Additional context -Related: #9049 (table captions and Architecture diagram, covering the other accessibility fixes) and #9048 (contrast). The `theme.favicon` setting should stay as is. +Related: #9049 (table captions and Architecture diagram, covering the other +accessibility fixes) and #9048 (contrast). The `theme.favicon` setting should +stay as is. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md index 6d7f68c5..88a386a7 100644 --- a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -6,25 +6,41 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Contributing page sends newcomers to a list of community resources without describing them or explaining how KubeVirt is run. A newcomer cannot tell which link answers their question. +The Contributing page sends newcomers to a list of community resources without +describing them or explaining how KubeVirt is run. A newcomer cannot tell which +link answers their question. Edit `docs/contributing.md`: -- Add a short "How the project is run" paragraph above the resource list. Name the maintainer group, explain that work is organized in SIGs (special interest groups), and state that decisions default to lazy consensus. -- Add a one-sentence description to each link in "Important community resources" that says what the reader finds there. -- Add links to the kubevirt/community resources a newcomer needs: the SIG list, the help-wanted guide, the community meeting document, and the maintainers list (`MAINTAINERS.md`). +- Add a short "How the project is run" paragraph above the resource list. Name + the maintainer group, explain that work is organized in SIGs (special interest + groups), and state that decisions default to lazy consensus. +- Add a one-sentence description to each link in "Important community resources" + that says what the reader finds there. +- Add links to the kubevirt/community resources a newcomer needs: the SIG list, + the help-wanted guide, the community meeting document, and the maintainers + list (`MAINTAINERS.md`). ## What you expected -A newcomer understands the project structure before following links, and each link states what it leads to. +A newcomer understands the project structure before following links, and each +link states what it leads to. ## URL - https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) -- https://github.com/kubevirt/community (`sig-list.md`, `GOVERNANCE.md`, `MAINTAINERS.md`) +- https://github.com/kubevirt/community (`sig-list.md`, `GOVERNANCE.md`, + `MAINTAINERS.md`) ## Additional context -Related: #9035, #9036, and #9037 (other additions to the same page; coordinate to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 (governance text on the Community page, which should use the same wording), and #9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list should the page link, the community one or a user guide one? +Related: #9035, #9036, and #9037 (other additions to the same page; coordinate +to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 +(governance text on the Community page, which should use the same wording), and +#9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list +should the page link, the community one or a user guide one? -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). +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). diff --git a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md index 08372f4b..ed4801fd 100644 --- a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -6,17 +6,25 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Contributing page does not say where contributors can ask questions, whether mentoring exists, or when documentation for a new feature is due. +The Contributing page does not say where contributors can ask questions, whether +mentoring exists, or when documentation for a new feature is due. Edit `docs/contributing.md` and repeat the help section in `CONTRIBUTING.md`: -- Add a "Where to ask for help" section. Name `#kubevirt-dev` on Kubernetes Slack for contributor questions and `#virtualization` for usage questions. Link the Slack invitation page. State that the weekly community meeting includes newcomer introductions, with the day, time, and Zoom link. Name the documentation approvers or a docs contact. -- State that the VEP (KubeVirt Enhancement Proposal) checklist requires the documentation pull request to be merged by code freeze. Link the VEP process. -- Add a short note on mentoring. The help-wanted guide promises "extra assistance" on `good first issue` items, so state how to request it. +- Add a "Where to ask for help" section. Name `#kubevirt-dev` on Kubernetes + Slack for contributor questions and `#virtualization` for usage questions. + Link the Slack invitation page. State that the weekly community meeting + includes newcomer introductions, with the day, time, and Zoom link. Name the + documentation approvers or a docs contact. +- State that the VEP (KubeVirt Enhancement Proposal) checklist requires the + documentation pull request to be merged by code freeze. Link the VEP process. +- Add a short note on mentoring. The help-wanted guide promises "extra + assistance" on `good first issue` items, so state how to request it. ## What you expected -A first-time contributor knows where to ask, when to join a meeting, whom to contact, and by when feature documentation must merge. +A first-time contributor knows where to ask, when to join a meeting, whom to +contact, and by when feature documentation must merge. ## URL @@ -25,8 +33,14 @@ A first-time contributor knows where to ask, when to join a meeting, whom to con ## Additional context -Questions for the maintainers: Does a mentoring or buddy arrangement for first-time contributors exist, or could one be offered? If not, remove the mentoring note. Who is the docs contact? +Questions for the maintainers: Does a mentoring or buddy arrangement for +first-time contributors exist, or could one be offered? If not, remove the +mentoring note. Who is the docs contact? -Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), #9034, #9036, #9037 (same page), and #9020. +Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), +#9034, #9036, #9037 (same page), and #9020. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md index c62e63a4..d4cb58dc 100644 --- a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -6,19 +6,27 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Contributing page gives generic advice to look for `good-first-issue` items. It does not link to a filtered list, and it does not explain how `good first issue` differs from `help wanted`. +The Contributing page gives generic advice to look for `good-first-issue` items. +It does not link to a filtered list, and it does not explain how +`good first issue` differs from `help wanted`. Edit `docs/contributing.md`: -- Replace the generic advice with a direct link to the filtered issue list for each repository where newcomers can work, for example kubevirt/user-guide, kubevirt/kubevirt, and kubevirt/kubevirt.github.io. -- Add a short explanation of both labels. Use `good first issue` for small, self-contained tasks and `help wanted` for slightly larger but still approachable tasks. +- Replace the generic advice with a direct link to the filtered issue list for + each repository where newcomers can work, for example kubevirt/user-guide, + kubevirt/kubevirt, and kubevirt/kubevirt.github.io. +- Add a short explanation of both labels. Use `good first issue` for small, + self-contained tasks and `help wanted` for slightly larger but still + approachable tasks. - Link the help-wanted guide in kubevirt/community. -Where `help wanted` is not applied consistently in a repository, note that in this issue so maintainers can label a few issues. +Where `help wanted` is not applied consistently in a repository, note that in +this issue so maintainers can label a few issues. ## What you expected -A newcomer clicks one link per repository and sees a current list of beginner-friendly issues, and knows what each label means. +A newcomer clicks one link per repository and sees a current list of +beginner-friendly issues, and knows what each label means. ## URL @@ -27,6 +35,11 @@ A newcomer clicks one link per repository and sees a current list of beginner-fr ## Additional context -Depends on #9038 (the label name must be standardized before linking the filter) and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, #9037. +Depends on #9038 (the label name must be standardized before linking the filter) +and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, +#9037. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md b/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md index cedff7e8..01deecf8 100644 --- a/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md +++ b/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md @@ -6,17 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Contributing page does not walk a newcomer through making a documentation change, and the build and test steps live only in the repository README. Code-minded newcomers also get a single link instead of a next step. +The Contributing page does not walk a newcomer through making a documentation +change, and the build and test steps live only in the repository README. +Code-minded newcomers also get a single link instead of a next step. Edit `docs/contributing.md`: -- Add a "Making your first documentation change" section that covers these steps: find or file an issue; comment to claim it; fork and branch; edit under `docs/` and update `.nav.yml`; run `make check_spelling` and `make check_links`; sign off with `git commit -s`; open the pull request; and what to expect from Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. -- Move the build and test steps from the README into this section, or link to them prominently. -- Add a "Contributing to the code" subsection that summarizes the kubevirt/kubevirt path in three or four steps: read `CONTRIBUTING.md`, follow `docs/getting-started.md` in kubevirt/kubevirt to build and run a local cluster, pick an issue, and open a draft pull request. +- Add a "Making your first documentation change" section that covers these + steps: find or file an issue; comment to claim it; fork and branch; edit under + `docs/` and update `.nav.yml`; run `make check_spelling` and + `make check_links`; sign off with `git commit -s`; open the pull request; and + what to expect from Prow (`ok-to-test`, `lgtm`, `approved`) and reviewers. +- Move the build and test steps from the README into this section, or link to + them prominently. +- Add a "Contributing to the code" subsection that summarizes the + kubevirt/kubevirt path in three or four steps: read `CONTRIBUTING.md`, follow + `docs/getting-started.md` in kubevirt/kubevirt to build and run a local + cluster, pick an issue, and open a draft pull request. ## What you expected -A newcomer completes a first documentation pull request using only this page, and a code-minded newcomer sees a short path into kubevirt/kubevirt. +A newcomer completes a first documentation pull request using only this page, +and a code-minded newcomer sees a short path into kubevirt/kubevirt. ## URL @@ -26,6 +37,11 @@ A newcomer completes a first documentation pull request using only this page, an ## Additional context -Related: #9020 (the same lifecycle in `CONTRIBUTING.md`; keep the two consistent or have one link the other), #9022 (pull request template), #9021 (style guide), and #9034 through #9036 (same page). +Related: #9020 (the same lifecycle in `CONTRIBUTING.md`; keep the two consistent +or have one link the other), #9022 (pull request template), #9021 (style guide), +and #9034 through #9036 (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). +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). diff --git a/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md b/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md index e3418072..64d6908b 100644 --- a/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md +++ b/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md @@ -6,18 +6,26 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -KubeVirt repositories carry two near-duplicate labels, the hyphenated `good-first-issue` and the GitHub-native `good first issue`. Issues with the hyphenated label do not appear in GitHub's "Contribute" tab or in good-first-issue discovery tooling, so newcomers cannot find them. Prow can also auto-close still-relevant issues that reach `lifecycle/rotten`. +KubeVirt repositories carry two near-duplicate labels, the hyphenated +`good-first-issue` and the GitHub-native `good first issue`. Issues with the +hyphenated label do not appear in GitHub's "Contribute" tab or in +good-first-issue discovery tooling, so newcomers cannot find them. Prow can also +auto-close still-relevant issues that reach `lifecycle/rotten`. Do the following: - Choose the GitHub-native `good first issue` (spaced) as the standard label. -- In each repository that has both labels, re-label issues from `good-first-issue` to `good first issue`, then retire the hyphenated label or alias it in the label configuration. +- In each repository that has both labels, re-label issues from + `good-first-issue` to `good first issue`, then retire the hyphenated label or + alias it in the label configuration. - Update the label reference on the Contributing page and in `CONTRIBUTING.md`. -- Apply `lifecycle/frozen`, or triage promptly, for still-relevant enhancements and documentation requests so they do not close for inactivity alone. +- Apply `lifecycle/frozen`, or triage promptly, for still-relevant enhancements + and documentation requests so they do not close for inactivity alone. ## What you expected -Each repository has one `good first issue` label, beginner issues appear in GitHub's Contribute tab, and the Contributing page names the same label. +Each repository has one `good first issue` label, beginner issues appear in +GitHub's Contribute tab, and the Contributing page names the same label. ## URL @@ -27,8 +35,13 @@ Each repository has one `good first issue` label, beginner issues appear in GitH ## Additional context -Question for the maintainers: Is label configuration managed centrally, for example in kubevirt/project-infra, so the change belongs there? +Question for the maintainers: Is label configuration managed centrally, for +example in kubevirt/project-infra, so the change belongs there? -Related: #9036 (filtered issue links depend on this label) and #9039 (backlog triage). +Related: #9036 (filtered issue links depend on this label) and #9039 (backlog +triage). -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). +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). diff --git a/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md b/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md index 400c203d..40b84add 100644 --- a/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md +++ b/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md @@ -6,18 +6,30 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide's open issues are largely unlabeled, and few if any are suitable for newcomers. Without labels and a regular triage routine, contributors cannot tell which issues are ready to work on. +The user guide's open issues are largely unlabeled, and few if any are suitable +for newcomers. Without labels and a regular triage routine, contributors cannot +tell which issues are ready to work on. Do the following: -- Triage the open backlog in https://github.com/kubevirt/user-guide/issues. Apply `kind/*` and `sig/documentation` labels to unlabeled issues, and apply `triage/accepted` to issues that are ready to be worked on. -- File a small, steady pool of beginner issues for documentation gaps, typos, and small feature-doc updates, and label them `good first issue`. -- Add a short "good first issue" checklist to the org-level issue templates: affected page, expected outcome, and pointers to relevant docs. Keep using the existing templates. -- Publish a lightweight triage cadence, for example a periodic documentation-issue triage during a SIG or community meeting, in `CONTRIBUTING.md` and on the Contributing page. State who labels, who accepts, and how staleness is handled. +- Triage the open backlog in https://github.com/kubevirt/user-guide/issues. + Apply `kind/*` and `sig/documentation` labels to unlabeled issues, and apply + `triage/accepted` to issues that are ready to be worked on. +- File a small, steady pool of beginner issues for documentation gaps, typos, + and small feature-doc updates, and label them `good first issue`. +- Add a short "good first issue" checklist to the org-level issue templates: + affected page, expected outcome, and pointers to relevant docs. Keep using the + existing templates. +- Publish a lightweight triage cadence, for example a periodic + documentation-issue triage during a SIG or community meeting, in + `CONTRIBUTING.md` and on the Contributing page. State who labels, who accepts, + and how staleness is handled. ## What you expected -Every open issue has a `kind/*` label and a triage state, at least a few `good first issue` items are always open, and contributors can read how often triage happens. +Every open issue has a `kind/*` label and a triage state, at least a few +`good first issue` items are always open, and contributors can read how often +triage happens. ## URL @@ -27,6 +39,11 @@ Every open issue has a `kind/*` label and a triage state, at least a few `good f ## Additional context -Questions for the maintainers: Which meeting could host triage, and who owns it? Related: #9038 (label standardization), #9036 (issue list links), #9024 (SIG home), and #9025 (pull request triage). Do #9038 first. +Questions for the maintainers: Which meeting could host triage, and who owns it? +Related: #9038 (label standardization), #9036 (issue list links), #9024 (SIG +home), and #9025 (pull request triage). Do #9038 first. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9040-add-governance-section.md b/analyses/2026/kubevirt/issues/9040-add-governance-section.md index a4099591..f171278e 100644 --- a/analyses/2026/kubevirt/issues/9040-add-governance-section.md +++ b/analyses/2026/kubevirt/issues/9040-add-governance-section.md @@ -6,27 +6,43 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The kubevirt.io Community page does not explain how the project is governed. Governance documents exist in kubevirt/community, but a visitor to the Community page has no summary and no links. +The kubevirt.io Community page does not explain how the project is governed. +Governance documents exist in kubevirt/community, but a visitor to the Community +page has no summary and no links. -Open a pull request against the kubevirt.io website repository (kubevirt/kubevirt.github.io) that adds a "Governance" section to the Community page: +Open a pull request against the kubevirt.io website repository +(kubevirt/kubevirt.github.io) that adds a "Governance" section to the Community +page: -- Write two or three sentences that state how KubeVirt is governed: a CNCF incubating project, run by a maintainer group, organized in SIGs and working groups, with lazy consensus and maintainer votes for decisions. -- Link `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and `sig-list.md` in kubevirt/community. +- Write two or three sentences that state how KubeVirt is governed: a CNCF + incubating project, run by a maintainer group, organized in SIGs and working + groups, with lazy consensus and maintainer votes for decisions. +- Link `GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, and + `sig-list.md` in kubevirt/community. -Verify each link target before publishing, and use the same wording as the "How the project is run" paragraph on the Contributing page. +Verify each link target before publishing, and use the same wording as the "How +the project is run" paragraph on the Contributing page. ## What you expected -A visitor to the Community page reads how KubeVirt is governed in under a minute and reaches each governance document in one click. +A visitor to the Community page reads how KubeVirt is governed in under a minute +and reaches each governance document in one click. ## URL - https://kubevirt.io/community/ -- https://github.com/kubevirt/community (`GOVERNANCE.md`, `MAINTAINERS.md`, `membership_policy.md`, `sig-list.md`) +- https://github.com/kubevirt/community (`GOVERNANCE.md`, `MAINTAINERS.md`, + `membership_policy.md`, `sig-list.md`) - https://github.com/kubevirt/kubevirt.github.io ## Additional context -Related: #9034 (Contributing page overview, same wording), #9030 (Community page in the guide), and #9024 (SIG list). Question for the maintainers: Is the project still described as CNCF incubating, and do maintainer votes apply to all decisions? +Related: #9034 (Contributing page overview, same wording), #9030 (Community page +in the guide), and #9024 (SIG list). Question for the maintainers: Is the +project still described as CNCF incubating, and do maintainer votes apply to all +decisions? -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). +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). diff --git a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md index 7cf49059..8ee1150a 100644 --- a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md +++ b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md @@ -6,9 +6,13 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -KubeVirt documentation is spread across `kubevirt/user-guide`, `kubevirt/kubevirt.github.io`, and `kubevirt/kubevirt/docs`. No repository states which kind of content belongs where, so contributors cannot tell where to add a new page and similar content ends up in more than one place. +KubeVirt documentation is spread across `kubevirt/user-guide`, +`kubevirt/kubevirt.github.io`, and `kubevirt/kubevirt/docs`. No repository +states which kind of content belongs where, so contributors cannot tell where to +add a new page and similar content ends up in more than one place. -Add a short "Where documentation lives" section to the README of each of these repositories: +Add a short "Where documentation lives" section to the README of each of these +repositories: - `kubevirt/user-guide` - `kubevirt/kubevirt.github.io` @@ -20,11 +24,14 @@ Use the same text in all three. The section states that: - Marketing, blog, and community content belongs on the website. - `kubevirt/kubevirt/docs` is for design and developer notes only. -Then link to the new section from `docs/contributing.md` in the user guide, for example from the "Other ways to contribute" section. +Then link to the new section from `docs/contributing.md` in the user guide, for +example from the "Other ways to contribute" section. ## What you expected -A contributor can read one short section in any of the three repositories and know which repository to use for a new page. The Contributing page links to that guidance. +A contributor can read one short section in any of the three repositories and +know which repository to use for a new page. The Contributing page links to that +guidance. ## URL @@ -35,6 +42,11 @@ A contributor can read one short section in any of the three repositories and kn ## Additional context -Related: #9060 adds a "Site infrastructure" section to the same READMEs, so coordinate the edits. Related: #9043 and #9044 act on the boundary this issue documents. +Related: #9060 adds a "Site infrastructure" section to the same READMEs, so +coordinate the edits. Related: #9043 and #9044 act on the boundary this issue +documents. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md b/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md index 8e3269f8..1ff28233 100644 --- a/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md +++ b/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md @@ -6,17 +6,27 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The KubeVirt API reference is published from a separate repository (`kubevirt/kubevirt.github.io`, at `kubevirt.github.io/api-reference`). The user guide navigation has no entry for it, so readers who need field-level details of a VirtualMachine or other API object must already know it exists. +The KubeVirt API reference is published from a separate repository +(`kubevirt/kubevirt.github.io`, at `kubevirt.github.io/api-reference`). The user +guide navigation has no entry for it, so readers who need field-level details of +a VirtualMachine or other API object must already know it exists. Make the API reference visible from the guide: -- Add an "API Reference" entry to `docs/.nav.yml` that links directly to `https://kubevirt.github.io/api-reference/`, or add a short landing page, for example `docs/api_reference.md`, and list it in `docs/.nav.yml`. -- If you add a landing page, explain that the reference is generated from the API types and published separately, link to it, and explain which API version it covers. Ask the maintainers whether the reference tracks `main` or the latest release, and state the answer on the page. -- Check that the awesome-nav plugin renders the external link and that it opens correctly. +- Add an "API Reference" entry to `docs/.nav.yml` that links directly to + `https://kubevirt.github.io/api-reference/`, or add a short landing page, for + example `docs/api_reference.md`, and list it in `docs/.nav.yml`. +- If you add a landing page, explain that the reference is generated from the + API types and published separately, link to it, and explain which API version + it covers. Ask the maintainers whether the reference tracks `main` or the + latest release, and state the answer on the page. +- Check that the awesome-nav plugin renders the external link and that it opens + correctly. ## What you expected -A reader browsing the guide navigation sees an API reference entry and reaches the reference in one click, without knowing which repository publishes it. +A reader browsing the guide navigation sees an API reference entry and reaches +the reference in one click, without knowing which repository publishes it. ## URL @@ -26,6 +36,10 @@ A reader browsing the guide navigation sees an API reference entry and reaches t ## Additional context -Related: #9041 documents which repository owns which content, and #9059 covers search across the guide and the website. +Related: #9041 documents which repository owns which content, and #9059 covers +search across the guide and the website. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md b/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md index 78b0d591..2f0cd5c7 100644 --- a/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md +++ b/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md @@ -6,29 +6,45 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The `docs/` directory in `kubevirt/kubevirt` contains pages that the user guide links to instead of hosting itself. Readers who follow those links leave the guide, lose its navigation and search, and read content that may not be maintained for end users. - -Audit the `kubevirt/kubevirt` repository and consolidate user-facing content in the guide: - -1. Start with the files the user guide already links to: `getting-started.md`, `architecture.md`, and `cloud-init.md`. -2. For each file, decide whether it is user-facing or a design or developer note. -3. Move the user-facing portions into the matching pages in `kubevirt/user-guide`, for example `docs/architecture/architecture.md` and the cloud-init page under `docs/user_workloads/`. -4. Replace each original file in `kubevirt/kubevirt` with a one-line pointer to the new guide page so search results and old links still resolve. +The `docs/` directory in `kubevirt/kubevirt` contains pages that the user guide +links to instead of hosting itself. Readers who follow those links leave the +guide, lose its navigation and search, and read content that may not be +maintained for end users. + +Audit the `kubevirt/kubevirt` repository and consolidate user-facing content in +the guide: + +1. Start with the files the user guide already links to: `getting-started.md`, + `architecture.md`, and `cloud-init.md`. +2. For each file, decide whether it is user-facing or a design or developer + note. +3. Move the user-facing portions into the matching pages in + `kubevirt/user-guide`, for example `docs/architecture/architecture.md` and + the cloud-init page under `docs/user_workloads/`. +4. Replace each original file in `kubevirt/kubevirt` with a one-line pointer to + the new guide page so search results and old links still resolve. 5. Update the user guide links that point at the old files. -Open the pull requests in both repositories. Ask the maintainers whether a file that mixes user and developer content should be split or left in place. +Open the pull requests in both repositories. Ask the maintainers whether a file +that mixes user and developer content should be split or left in place. ## What you expected -The guide hosts the user-facing content for these three topics, and the files in `kubevirt/kubevirt/docs` point readers to the guide. +The guide hosts the user-facing content for these three topics, and the files in +`kubevirt/kubevirt/docs` point readers to the guide. ## URL -- https://kubevirt.io/user-guide/architecture/architecture/ (`docs/architecture/architecture.md`) +- https://kubevirt.io/user-guide/architecture/architecture/ + (`docs/architecture/architecture.md`) - https://github.com/kubevirt/kubevirt/tree/main/docs ## Additional context -Depends on the content boundary decision in #9041. Related: #9044 applies the same audit to the CDI documentation. +Depends on the content boundary decision in #9041. Related: #9044 applies the +same audit to the CDI documentation. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md b/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md index 1f809675..ab867587 100644 --- a/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md +++ b/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md @@ -6,26 +6,42 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Six pages in the guide's storage content link out to the `doc/` directory of the Containerized Data Importer (CDI) repository, `kubevirt/containerized-data-importer`. Readers lose the guide's navigation and search when they follow those links, and the guide never explains why this content lives elsewhere. +Six pages in the guide's storage content link out to the `doc/` directory of the +Containerized Data Importer (CDI) repository, +`kubevirt/containerized-data-importer`. Readers lose the guide's navigation and +search when they follow those links, and the guide never explains why this +content lives elsewhere. Triage the CDI pages that the guide links to and pick one outcome for each page: -- Move the page into the guide's `docs/storage/` section and add it to `docs/storage/.nav.yml`, leaving a one-line pointer in the CDI repository. -- Keep the page in CDI and list it on a new "CDI reference documentation" page in `docs/storage/`. The page explains why the remaining CDI content stays in its own repository and links each page with a one-sentence summary. +- Move the page into the guide's `docs/storage/` section and add it to + `docs/storage/.nav.yml`, leaving a one-line pointer in the CDI repository. +- Keep the page in CDI and list it on a new "CDI reference documentation" page + in `docs/storage/`. The page explains why the remaining CDI content stays in + its own repository and links each page with a one-sentence summary. -Start by listing the six storage pages with their CDI links, for example in `docs/storage/containerized_data_importer.md`. Ask the CDI maintainers which pages they prefer to keep. +Start by listing the six storage pages with their CDI links, for example in +`docs/storage/containerized_data_importer.md`. Ask the CDI maintainers which +pages they prefer to keep. ## What you expected -Every CDI link in the storage section either leads to a page hosted in the guide or to a clearly described reference page that explains why the content lives in the CDI repository. +Every CDI link in the storage section either leads to a page hosted in the guide +or to a clearly described reference page that explains why the content lives in +the CDI repository. ## URL -- https://kubevirt.io/user-guide/storage/containerized_data_importer/ (`docs/storage/containerized_data_importer.md`) +- https://kubevirt.io/user-guide/storage/containerized_data_importer/ + (`docs/storage/containerized_data_importer.md`) - https://github.com/kubevirt/containerized-data-importer/tree/main/doc ## Additional context -Depends on the content boundary decision in #9041. Related: #9043 applies the same audit to `kubevirt/kubevirt/docs`. +Depends on the content boundary decision in #9041. Related: #9043 applies the +same audit to `kubevirt/kubevirt/docs`. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md b/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md index 6edbac56..25c99e97 100644 --- a/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md +++ b/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md @@ -6,19 +6,32 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide is built with MkDocs and Material for MkDocs, and the main website (`kubevirt/kubevirt.github.io`) is built with Jekyll. The two sites have different generators, themes, and maintenance skills. This split makes search, navigation, branding, and analytics harder to keep consistent, and no document records whether it is intentional. - -Run a short evaluation and record the decision in a written decision record, for example a comment on this issue or a page in `kubevirt/community`: - -- Compare the cost of three options: keep both toolchains, move the website pages into the user guide repository, or bring the guide into the website repository as a Git submodule. -- Evaluate moving the website to Material for MkDocs or another generator with a supported theme, such as Hugo or Docusaurus, so one skill set covers both sites. +The user guide is built with MkDocs and Material for MkDocs, and the main +website (`kubevirt/kubevirt.github.io`) is built with Jekyll. The two sites have +different generators, themes, and maintenance skills. This split makes search, +navigation, branding, and analytics harder to keep consistent, and no document +records whether it is intentional. + +Run a short evaluation and record the decision in a written decision record, for +example a comment on this issue or a page in `kubevirt/community`: + +- Compare the cost of three options: keep both toolchains, move the website + pages into the user guide repository, or bring the guide into the website + repository as a Git submodule. +- Evaluate moving the website to Material for MkDocs or another generator with a + supported theme, such as Hugo or Docusaurus, so one skill set covers both + sites. - List the maintainers who must agree. -If the sites stay separate, add a short note to the README of both repositories that states the reasons (different generators, maintainers, and audiences). If the project plans to converge, keep this issue open as the tracking issue even when the migration is deferred. +If the sites stay separate, add a short note to the README of both repositories +that states the reasons (different generators, maintainers, and audiences). If +the project plans to converge, keep this issue open as the tracking issue even +when the migration is deferred. ## What you expected -The decision about the two toolchains is recorded, with reasons, and both READMEs reflect it. +The decision about the two toolchains is recorded, with reasons, and both +READMEs reflect it. ## URL @@ -28,6 +41,11 @@ The decision about the two toolchains is recorded, with reasons, and both README ## Additional context -Related: #9060 documents site infrastructure ownership in the same READMEs. Related: #9059 (unified search) and #9052 (brand reference) become simpler if the sites converge. +Related: #9060 documents site infrastructure ownership in the same READMEs. +Related: #9059 (unified search) and #9052 (brand reference) become simpler if +the sites converge. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md b/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md index a406d1e3..b64e0b94 100644 --- a/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md +++ b/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md @@ -6,20 +6,30 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide footer does not carry the copyright, CNCF, and trademark text that the main website footer shows. The two properties therefore read as separate projects, and the guide lacks the legal links the project footer should include. +The user guide footer does not carry the copyright, CNCF, and trademark text +that the main website footer shows. The two properties therefore read as +separate projects, and the guide lacks the legal links the project footer should +include. Update the guide footer in `kubevirt/user-guide`: -- Set `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"` in `mkdocs.yml`. -- Add `overrides/partials/copyright.html` (or a `footer.html` override) and set `theme.custom_dir: overrides` in `mkdocs.yml`. -- In the override, append the sentence "We are a Cloud Native Computing Foundation incubating project", the CNCF logo linked to `https://www.cncf.io`, and a link to `https://lfprojects.org/policies/` for trademark and terms. -- Copy the wording and links from `_includes/footer.html` in `kubevirt/kubevirt.github.io` so both footers match. +- Set `copyright: "Copyright © KubeVirt a Series of LF Projects, LLC"` in + `mkdocs.yml`. +- Add `overrides/partials/copyright.html` (or a `footer.html` override) and set + `theme.custom_dir: overrides` in `mkdocs.yml`. +- In the override, append the sentence "We are a Cloud Native Computing + Foundation incubating project", the CNCF logo linked to `https://www.cncf.io`, + and a link to `https://lfprojects.org/policies/` for trademark and terms. +- Copy the wording and links from `_includes/footer.html` in + `kubevirt/kubevirt.github.io` so both footers match. -Build the site locally with `mkdocs serve` and check the footer in both the light and dark schemes. +Build the site locally with `mkdocs serve` and check the footer in both the +light and dark schemes. ## What you expected -Every guide page shows the same copyright line, CNCF statement and logo, and LF Projects policies link as the main website. +Every guide page shows the same copyright line, CNCF statement and logo, and LF +Projects policies link as the main website. ## URL @@ -29,6 +39,10 @@ Every guide page shows the same copyright line, CNCF statement and logo, and LF ## Additional context -Related: #9047 fixes the website footer, and #9032 adds repository and social links to the guide footer. Edit the same override file in both issues. +Related: #9047 fixes the website footer, and #9032 adds repository and social +links to the guide footer. Edit the same override file in both issues. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9047-fix-website-footer.md b/analyses/2026/kubevirt/issues/9047-fix-website-footer.md index 59623ed2..b5514b99 100644 --- a/analyses/2026/kubevirt/issues/9047-fix-website-footer.md +++ b/analyses/2026/kubevirt/issues/9047-fix-website-footer.md @@ -6,18 +6,29 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -This issue affects `kubevirt/kubevirt.github.io` (the main website) and `kubevirt/user-guide`. The website copyright line omits the © symbol, the two repositories lack a root `CODE_OF_CONDUCT.md`, and the website repository has no `CONTRIBUTING.md`. The maturity statement in each footer also has no owner and can go stale when the CNCF status changes. +This issue affects `kubevirt/kubevirt.github.io` (the main website) and +`kubevirt/user-guide`. The website copyright line omits the © symbol, the two +repositories lack a root `CODE_OF_CONDUCT.md`, and the website repository has no +`CONTRIBUTING.md`. The maturity statement in each footer also has no owner and +can go stale when the CNCF status changes. Make these changes: -1. In `_includes/footer.html` of `kubevirt/kubevirt.github.io`, change the copyright line to "Copyright © KubeVirt a Series of LF Projects, LLC". -2. Add a root `CODE_OF_CONDUCT.md` to both `kubevirt/user-guide` and `kubevirt/kubevirt.github.io` that links to the code of conduct in `kubevirt/community`. -3. Add a `CONTRIBUTING.md` to `kubevirt/kubevirt.github.io` that points to the contributing content in its README and to the user guide Contributing page. -4. Add a note to each repository's README that names the footer file to edit when the project's CNCF maturity level changes: `_includes/footer.html` for the website and the footer override for the guide. +1. In `_includes/footer.html` of `kubevirt/kubevirt.github.io`, change the + copyright line to "Copyright © KubeVirt a Series of LF Projects, LLC". +2. Add a root `CODE_OF_CONDUCT.md` to both `kubevirt/user-guide` and + `kubevirt/kubevirt.github.io` that links to the code of conduct in + `kubevirt/community`. +3. Add a `CONTRIBUTING.md` to `kubevirt/kubevirt.github.io` that points to the + contributing content in its README and to the user guide Contributing page. +4. Add a note to each repository's README that names the footer file to edit + when the project's CNCF maturity level changes: `_includes/footer.html` for + the website and the footer override for the guide. ## What you expected -Both repositories contain the community health files, the website footer shows the © symbol, and a maintainer can find where to update the maturity statement. +Both repositories contain the community health files, the website footer shows +the © symbol, and a maintainer can find where to update the maturity statement. ## URL @@ -27,6 +38,10 @@ Both repositories contain the community health files, the website footer shows t ## Additional context -Related: #9046 updates the user guide footer. Add the maturity note to the guide README only after #9046 creates the footer override. +Related: #9046 updates the user guide footer. Add the maturity note to the guide +README only after #9046 creates the footer override. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md b/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md index fae4c6ba..37c12c03 100644 --- a/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md +++ b/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md @@ -6,18 +6,31 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The guide uses the teal `#0db2b6` as `--md-primary-fg-color` in `docs/stylesheets/extra.css`. White header and tab text on this teal falls below the 4.5:1 contrast ratio that WCAG AA requires. Links also rely on a `filter: brightness(80%)` rule rather than explicit colors. In addition, `#0db2b6` does not appear in the `$kv-color--green-*` scale that the main website documents, so the two sites use different greens. +The guide uses the teal `#0db2b6` as `--md-primary-fg-color` in +`docs/stylesheets/extra.css`. White header and tab text on this teal falls below +the 4.5:1 contrast ratio that WCAG AA requires. Links also rely on a +`filter: brightness(80%)` rule rather than explicit colors. In addition, +`#0db2b6` does not appear in the `$kv-color--green-*` scale that the main +website documents, so the two sites use different greens. Update `docs/stylesheets/extra.css`: -- Darken `--md-primary-fg-color` to a teal with at least 4.5:1 contrast against white (for example `#007a7e` or darker), or keep the brand teal for decorative elements and set the header and tab text to a dark foreground. -- Replace the `filter: brightness(80%)` rule with explicit `--md-typeset-a-color` values for the light and dark schemes, each with at least 4.5:1 contrast. -- Choose the final color from the documented website scale (for example `$kv-color--green-300`, `#00aab2`), or ask the website maintainers whether to add `#0db2b6` to the scale. -- Check both schemes with a contrast checker and record the ratios in the pull request. +- Darken `--md-primary-fg-color` to a teal with at least 4.5:1 contrast against + white (for example `#007a7e` or darker), or keep the brand teal for decorative + elements and set the header and tab text to a dark foreground. +- Replace the `filter: brightness(80%)` rule with explicit + `--md-typeset-a-color` values for the light and dark schemes, each with at + least 4.5:1 contrast. +- Choose the final color from the documented website scale (for example + `$kv-color--green-300`, `#00aab2`), or ask the website maintainers whether to + add `#0db2b6` to the scale. +- Check both schemes with a contrast checker and record the ratios in the pull + request. ## What you expected -Header text, tab text, and links meet 4.5:1 contrast in both color schemes, and the guide draws its primary color from the same scale as the website. +Header text, tab text, and links meet 4.5:1 contrast in both color schemes, and +the guide draws its primary color from the same scale as the website. ## URL @@ -26,6 +39,10 @@ Header text, tab text, and links meet 4.5:1 contrast in both color schemes, and ## Additional context -Related: #9052 publishes the brand reference that lists the canonical color scale. +Related: #9052 publishes the brand reference that lists the canonical color +scale. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md b/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md index 89ab2f7a..bdacfd09 100644 --- a/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md +++ b/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md @@ -6,34 +6,52 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Wide tables and the Architecture page diagram do not work well on phones and with screen readers. +Wide tables and the Architecture page diagram do not work well on phones and +with screen readers. ### Tables -`docs/stylesheets/extra.css` contains a `display: table; width: max-content` override. Check on a phone whether the tables in the Arm64 feature-gate status and device status pages scroll horizontally or overflow the page. If they overflow, remove the override or scope it to specific tables with an `attr_list` class. Then add a short sentence above each wide status table that states what the table shows. +`docs/stylesheets/extra.css` contains a `display: table; width: max-content` +override. Check on a phone whether the tables in the Arm64 feature-gate status +and device status pages scroll horizontally or overflow the page. If they +overflow, remove the override or scope it to specific tables with an `attr_list` +class. Then add a short sentence above each wide status table that states what +the table shows. ### Architecture diagram -The Architecture page shows the stack as an ASCII diagram, which screen readers read as noise and phones wrap badly. Replace it with one of these: +The Architecture page shows the stack as an ASCII diagram, which screen readers +read as noise and phones wrap badly. Replace it with one of these: - An image with descriptive alt text. -- A Mermaid diagram. Enable it by adding a `mermaid` custom fence to the existing `pymdownx.superfences` entry in `mkdocs.yml`. +- A Mermaid diagram. Enable it by adding a `mermaid` custom fence to the + existing `pymdownx.superfences` entry in `mkdocs.yml`. -Add a one-paragraph prose description of the layers below the diagram so every reader gets the same information. +Add a one-paragraph prose description of the layers below the diagram so every +reader gets the same information. ## What you expected -Tables scroll inside the page on a phone, each wide table has an introductory sentence, and the Architecture page presents the stack as an accessible diagram with a prose description. +Tables scroll inside the page on a phone, each wide table has an introductory +sentence, and the Architecture page presents the stack as an accessible diagram +with a prose description. ## URL -- https://kubevirt.io/user-guide/cluster_admin/feature_gate_status_on_Arm64/ (`docs/cluster_admin/feature_gate_status_on_Arm64.md`) -- https://kubevirt.io/user-guide/cluster_admin/device_status_on_Arm64/ (`docs/cluster_admin/device_status_on_Arm64.md`) -- https://kubevirt.io/user-guide/architecture/architecture/ (`docs/architecture/architecture.md`) +- https://kubevirt.io/user-guide/cluster_admin/feature_gate_status_on_Arm64/ + (`docs/cluster_admin/feature_gate_status_on_Arm64.md`) +- https://kubevirt.io/user-guide/cluster_admin/device_status_on_Arm64/ + (`docs/cluster_admin/device_status_on_Arm64.md`) +- https://kubevirt.io/user-guide/architecture/architecture/ + (`docs/architecture/architecture.md`) - `docs/stylesheets/extra.css`, `mkdocs.yml` ## Additional context -Related: #9033 fixes the logo alt text, and #9048 also edits `docs/stylesheets/extra.css`. +Related: #9033 fixes the logo alt text, and #9048 also edits +`docs/stylesheets/extra.css`. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md b/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md index f3ea1965..25e24290 100644 --- a/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md +++ b/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md @@ -6,31 +6,48 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Two guide pages are far longer than readers can scan. `docs/storage/disks_and_volumes.md` runs to about 2,160 lines and `docs/network/interfaces_and_networks.md` to about 900 lines. Readers have to scroll through a long right-hand table of contents to find one volume type or binding method, and links to sections break when headings change. +Two guide pages are far longer than readers can scan. +`docs/storage/disks_and_volumes.md` runs to about 2,160 lines and +`docs/network/interfaces_and_networks.md` to about 900 lines. Readers have to +scroll through a long right-hand table of contents to find one volume type or +binding method, and links to sections break when headings change. Split both pages into sub-pages: -- **Disks and Volumes:** keep an overview page with the disk and volume concepts and a table linking to one sub-page per volume type, for example `docs/storage/volumes/`. -- **Interfaces and Networks:** separate the interface binding methods from the network attachment content, each in its own page, and keep an overview page that links to both. +- **Disks and Volumes:** keep an overview page with the disk and volume concepts + and a table linking to one sub-page per volume type, for example + `docs/storage/volumes/`. +- **Interfaces and Networks:** separate the interface binding methods from the + network attachment content, each in its own page, and keep an overview page + that links to both. For each split: 1. Move the content without rewriting it. 2. Update `docs/storage/.nav.yml` and `docs/network/.nav.yml`. -3. Add an entry to the `redirects` map in `mkdocs.yml` for any moved anchor or page so existing links keep working. +3. Add an entry to the `redirects` map in `mkdocs.yml` for any moved anchor or + page so existing links keep working. 4. Fix internal links with `grep` for the old paths. ## What you expected -Each resulting page is a manageable length, the overview pages guide readers to the right sub-page, and existing URLs keep resolving. +Each resulting page is a manageable length, the overview pages guide readers to +the right sub-page, and existing URLs keep resolving. ## URL -- https://kubevirt.io/user-guide/storage/disks_and_volumes/ (`docs/storage/disks_and_volumes.md`) -- https://kubevirt.io/user-guide/network/interfaces_and_networks/ (`docs/network/interfaces_and_networks.md`) +- https://kubevirt.io/user-guide/storage/disks_and_volumes/ + (`docs/storage/disks_and_volumes.md`) +- https://kubevirt.io/user-guide/network/interfaces_and_networks/ + (`docs/network/interfaces_and_networks.md`) ## Additional context -Related: #9051 splits the Live Migration and Release Notes pages, and #9009 adds landing pages to the Storage and Network sections. Coordinate navigation edits with those issues. +Related: #9051 splits the Live Migration and Release Notes pages, and #9009 adds +landing pages to the Storage and Network sections. Coordinate navigation edits +with those issues. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md b/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md index e14f6db9..a7f5b204 100644 --- a/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md +++ b/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md @@ -6,15 +6,22 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -`docs/compute/live_migration.md` has about 650 lines and `docs/release_notes.md` has about 3,050 lines. Both are too long to navigate, and the Release Notes tab opens at the top of the page, which is the oldest-first or the longest scroll for readers who want the newest release. +`docs/compute/live_migration.md` has about 650 lines and `docs/release_notes.md` +has about 3,050 lines. Both are too long to navigate, and the Release Notes tab +opens at the top of the page, which is the oldest-first or the longest scroll +for readers who want the newest release. ### Live Migration -Keep the overview and basic procedure on the Live Migration page. Move the migration strategies and the migration network configuration to sub-pages under `docs/compute/` and link them from the overview. +Keep the overview and basic procedure on the Live Migration page. Move the +migration strategies and the migration network configuration to sub-pages under +`docs/compute/` and link them from the overview. ### Release Notes -Split the page into one page per minor release, or paginate it. Create an index page that lists the releases newest first. Set the Release Notes tab in `docs/.nav.yml` so it opens the newest release. +Split the page into one page per minor release, or paginate it. Create an index +page that lists the releases newest first. Set the Release Notes tab in +`docs/.nav.yml` so it opens the newest release. For both pages: @@ -25,15 +32,22 @@ For both pages: ## What you expected -Each page is a manageable length, the Release Notes tab opens the newest release, and existing links still resolve. +Each page is a manageable length, the Release Notes tab opens the newest +release, and existing links still resolve. ## URL -- https://kubevirt.io/user-guide/compute/live_migration/ (`docs/compute/live_migration.md`) +- https://kubevirt.io/user-guide/compute/live_migration/ + (`docs/compute/live_migration.md`) - https://kubevirt.io/user-guide/release_notes/ (`docs/release_notes.md`) ## Additional context -Related: #9050 splits the Disks and Volumes and Interfaces and Networks pages, and #9008 changes where Release Notes sits in the navigation. Coordinate `docs/.nav.yml` edits with #9008. +Related: #9050 splits the Disks and Volumes and Interfaces and Networks pages, +and #9008 changes where Release Notes sits in the navigation. Coordinate +`docs/.nav.yml` edits with #9008. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md index f52c2018..79ad54e8 100644 --- a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -6,19 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The brand assets of KubeVirt live in several places. The website defines a `$kv-color--green-*` scale, and the user guide uses its own colors in `docs/stylesheets/extra.css`. No single page lists the canonical logo files, colors, and typefaces, so the two sites drift apart when the palette changes. +The brand assets of KubeVirt live in several places. The website defines a +`$kv-color--green-*` scale, and the user guide uses its own colors in +`docs/stylesheets/extra.css`. No single page lists the canonical logo files, +colors, and typefaces, so the two sites drift apart when the palette changes. -Publish a short brand reference in either `kubevirt/kubevirt.github.io` or `kubevirt/community`. Ask the maintainers which repository is the better home. The reference lists: +Publish a short brand reference in either `kubevirt/kubevirt.github.io` or +`kubevirt/community`. Ask the maintainers which repository is the better home. +The reference lists: -- The canonical logo files: the icon and the horizontal wordmark, with links to the files. +- The canonical logo files: the icon and the horizontal wordmark, with links to + the files. - The hex values of the `$kv-color--green-*` scale. - The approved typefaces. -Then add a comment at the top of `docs/stylesheets/extra.css` in the user guide that cites the reference URL and tells editors to update the guide when the palette changes. +Then add a comment at the top of `docs/stylesheets/extra.css` in the user guide +that cites the reference URL and tells editors to update the guide when the +palette changes. ## What you expected -One page is the source of truth for logos, colors, and typefaces, and the guide stylesheet points to it. +One page is the source of truth for logos, colors, and typefaces, and the guide +stylesheet points to it. ## URL @@ -28,6 +37,11 @@ One page is the source of truth for logos, colors, and typefaces, and the guide ## Additional context -Related: #9048 aligns the guide's primary color with the website scale, and #9033 fixes the logo alt text. Complete #9048 first so the reference lists the final values. +Related: #9048 aligns the guide's primary color with the website scale, and +#9033 fixes the logo alt text. Complete #9048 first so the reference lists the +final values. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9053-add-adopters-page.md b/analyses/2026/kubevirt/issues/9053-add-adopters-page.md index 7a8e6213..7cef52d3 100644 --- a/analyses/2026/kubevirt/issues/9053-add-adopters-page.md +++ b/analyses/2026/kubevirt/issues/9053-add-adopters-page.md @@ -6,18 +6,27 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -This issue affects the main website, `kubevirt/kubevirt.github.io`. KubeVirt has two published CNCF case studies (NTT Docomo Business and Swisscom), but `kubevirt.io` does not link to them. The landing page shows an End Users logo wall, and evaluators have no single page that shows adoption evidence. +This issue affects the main website, `kubevirt/kubevirt.github.io`. KubeVirt has +two published CNCF case studies (NTT Docomo Business and Swisscom), but +`kubevirt.io` does not link to them. The landing page shows an End Users logo +wall, and evaluators have no single page that shows adoption evidence. Make two changes in `kubevirt/kubevirt.github.io`: -1. Add a "Case Studies" block beneath the End Users logo wall on the landing page that links to the two CNCF case studies. The content already exists, so this change needs no new writing. -2. Create an `/adopters/` (or `/case-studies/`) page that renders the full adopters table with the columns type, name, since, and use case, and links to the CNCF case studies. Add the page to `_data/site_nav_pages.yml`. +1. Add a "Case Studies" block beneath the End Users logo wall on the landing + page that links to the two CNCF case studies. The content already exists, so + this change needs no new writing. +2. Create an `/adopters/` (or `/case-studies/`) page that renders the full + adopters table with the columns type, name, since, and use case, and links to + the CNCF case studies. Add the page to `_data/site_nav_pages.yml`. -Build the table from `_data/adopters.yml`, which the website already generates from `ADOPTERS.md`, rather than copying data by hand. +Build the table from `_data/adopters.yml`, which the website already generates +from `ADOPTERS.md`, rather than copying data by hand. ## What you expected -An evaluator reaches the two case studies from the landing page and finds all adopters on one page that is listed in the site navigation. +An evaluator reaches the two case studies from the landing page and finds all +adopters on one page that is listed in the site navigation. ## URL @@ -27,6 +36,10 @@ An evaluator reaches the two case studies from the landing page and finds all ad ## Additional context -Related: #9054 adds the use-case text and KubeVirt-specific vendor links to the same data and page. +Related: #9054 adds the use-case text and KubeVirt-specific vendor links to the +same data and 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). +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). diff --git a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md index a2853e02..b4588d4e 100644 --- a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -6,20 +6,30 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -This issue affects the main website, `kubevirt/kubevirt.github.io`. The adopters logo wall shows only logos. The "Use-Case" text that each adopter supplies in `ADOPTERS.md` never reaches the site, and vendor logos link to corporate homepages that do not mention KubeVirt. +This issue affects the main website, `kubevirt/kubevirt.github.io`. The adopters +logo wall shows only logos. The "Use-Case" text that each adopter supplies in +`ADOPTERS.md` never reaches the site, and vendor logos link to corporate +homepages that do not mention KubeVirt. Make these changes: -1. Extend `adopters.py` and `_data/adopters.yml` so they carry the "Use-Case" text from `ADOPTERS.md`. -2. Show the text on the website as a tooltip or an expandable card on each logo, so the wall becomes a set of short, attributed testimonials. -3. For each `ADOPTERS.md` vendor entry whose link is a corporate homepage, ask the vendor for a URL that mentions KubeVirt support or their KubeVirt-based product, and update the link. -4. Ask the maintainers whether to drop the logo from the Vendors section when a vendor has no such page. +1. Extend `adopters.py` and `_data/adopters.yml` so they carry the "Use-Case" + text from `ADOPTERS.md`. +2. Show the text on the website as a tooltip or an expandable card on each logo, + so the wall becomes a set of short, attributed testimonials. +3. For each `ADOPTERS.md` vendor entry whose link is a corporate homepage, ask + the vendor for a URL that mentions KubeVirt support or their KubeVirt-based + product, and update the link. +4. Ask the maintainers whether to drop the logo from the Vendors section when a + vendor has no such page. -Check that the tooltip or card works with keyboard navigation and on touch devices. +Check that the tooltip or card works with keyboard navigation and on touch +devices. ## What you expected -Each adopter logo shows a short use case, and vendor logos link to pages that mention KubeVirt. +Each adopter logo shows a short use case, and vendor logos link to pages that +mention KubeVirt. ## URL @@ -29,6 +39,10 @@ Each adopter logo shows a short use case, and vendor logos link to pages that me ## Additional context -Related: #9053 adds the adopters page that should display the same use-case data. Land #9053 first, or share the data changes between both pull requests. +Related: #9053 adds the adopters page that should display the same use-case +data. Land #9053 first, or share the data changes between both pull requests. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9055-add-blog-categories.md b/analyses/2026/kubevirt/issues/9055-add-blog-categories.md index 9a4be671..90402981 100644 --- a/analyses/2026/kubevirt/issues/9055-add-blog-categories.md +++ b/analyses/2026/kubevirt/issues/9055-add-blog-categories.md @@ -6,18 +6,26 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -This issue affects the main website, `kubevirt/kubevirt.github.io`. Blog posts use only the `news` and `uncategorized` categories, so the blog index cannot filter posts by what readers care about, such as a release, a feature, community news, or a user story. +This issue affects the main website, `kubevirt/kubevirt.github.io`. Blog posts +use only the `news` and `uncategorized` categories, so the blog index cannot +filter posts by what readers care about, such as a release, a feature, community +news, or a user story. Add a category or tag scheme to the website blog: -1. Define a small, documented set of categories, for example `release`, `feature`, `community`, and `user-story`. Ask the maintainers to confirm the list. -2. Add the new category values to the front matter of the recent posts, and backfill enough of them that each category has several entries. -3. Update the blog index layout so readers can filter by category, or add one page per category. +1. Define a small, documented set of categories, for example `release`, + `feature`, `community`, and `user-story`. Ask the maintainers to confirm the + list. +2. Add the new category values to the front matter of the recent posts, and + backfill enough of them that each category has several entries. +3. Update the blog index layout so readers can filter by category, or add one + page per category. 4. Document the scheme in the website README so new posts use it. ## What you expected -A reader can filter the blog by release, feature, community, and user story, and new posts follow the documented scheme. +A reader can filter the blog by release, feature, community, and user story, and +new posts follow the documented scheme. ## URL @@ -26,6 +34,10 @@ A reader can filter the blog by release, feature, community, and user story, and ## Additional context -The assessment did not specify the final category names, so treat the list above as a proposal for the maintainers to confirm. +The assessment did not specify the final category names, so treat the list above +as a proposal for the maintainers to confirm. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md b/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md index fc49fcff..836216fa 100644 --- a/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md +++ b/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md @@ -6,18 +6,29 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The user guide has no analytics, so the project cannot see which pages readers use, which search terms they enter, or which URLs return a 404. Missing redirects therefore go unnoticed. The main website already loads an Adobe Analytics tag. +The user guide has no analytics, so the project cannot see which pages readers +use, which search terms they enter, or which URLs return a 404. Missing +redirects therefore go unnoticed. The main website already loads an Adobe +Analytics tag. Enable analytics on the guide in `kubevirt/user-guide`: -1. Add the analytics snippet. Either add an `extra.analytics` block to `mkdocs.yml` (the Material theme supports Google Analytics 4), or add an `overrides/main.html` partial that loads the same Adobe Analytics tag as the website. Ask the maintainers which service to use. -2. Load the snippet only in production. Template it from the Netlify `CONTEXT` variable in the `netlify.toml` build command, so it is injected only when `CONTEXT` equals `production`. -3. Create a recurring 404 report, for example a saved report filtered on the not-found page title. -4. Use the report to add missing entries to the `redirects` map in `mkdocs.yml`, and describe the process in `README.md`. +1. Add the analytics snippet. Either add an `extra.analytics` block to + `mkdocs.yml` (the Material theme supports Google Analytics 4), or add an + `overrides/main.html` partial that loads the same Adobe Analytics tag as the + website. Ask the maintainers which service to use. +2. Load the snippet only in production. Template it from the Netlify `CONTEXT` + variable in the `netlify.toml` build command, so it is injected only when + `CONTEXT` equals `production`. +3. Create a recurring 404 report, for example a saved report filtered on the + not-found page title. +4. Use the report to add missing entries to the `redirects` map in `mkdocs.yml`, + and describe the process in `README.md`. ## What you expected -Production page views, search terms, and 404 hits are captured, previews send no data, and the 404 report drives redirect fixes. +Production page views, search terms, and 404 hits are captured, previews send no +data, and the 404 report drives redirect fixes. ## URL @@ -27,6 +38,11 @@ Production page views, search terms, and 404 hits are captured, previews send no ## Additional context -Related: #9057 gates analytics on the website, #9058 fixes the guide's preview builds in `netlify.toml`, and #9060 records who owns the analytics account. Edit `netlify.toml` in coordination with #9058. +Related: #9057 gates analytics on the website, #9058 fixes the guide's preview +builds in `netlify.toml`, and #9060 records who owns the analytics account. Edit +`netlify.toml` in coordination with #9058. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md b/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md index 550f840f..53f25a4e 100644 --- a/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md +++ b/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md @@ -6,18 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -This issue affects the main website, `kubevirt/kubevirt.github.io`. The `robots.txt` file on kubevirt.io points to an incorrect sitemap URL and does not list the user guide sitemap. The website also loads the `dpal.js` analytics script in every build, so preview and branch deploys can pollute production data, and nothing explicitly asks search engines to skip non-production deploys. +This issue affects the main website, `kubevirt/kubevirt.github.io`. The +`robots.txt` file on kubevirt.io points to an incorrect sitemap URL and does not +list the user guide sitemap. The website also loads the `dpal.js` analytics +script in every build, so preview and branch deploys can pollute production +data, and nothing explicitly asks search engines to skip non-production deploys. Make these changes in `kubevirt/kubevirt.github.io`: -1. Correct the sitemap URL in `robots.txt` to `https://kubevirt.io/sitemap.xml`, and add a second line, `Sitemap: https://kubevirt.io/user-guide/sitemap.xml`. -2. In `_includes/head.html`, wrap the `dpal.js` include in a check on `jekyll.environment == "production"`. -3. Set `JEKYLL_ENV=production` only in the Netlify production context in `netlify.toml`. -4. Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` file or a `[context.deploy-preview]` and `[context.branch-deploy]` section in `netlify.toml`. +1. Correct the sitemap URL in `robots.txt` to `https://kubevirt.io/sitemap.xml`, + and add a second line, `Sitemap: https://kubevirt.io/user-guide/sitemap.xml`. +2. In `_includes/head.html`, wrap the `dpal.js` include in a check on + `jekyll.environment == "production"`. +3. Set `JEKYLL_ENV=production` only in the Netlify production context in + `netlify.toml`. +4. Emit `X-Robots-Tag: noindex` for non-production deploys from a `_headers` + file or a `[context.deploy-preview]` and `[context.branch-deploy]` section in + `netlify.toml`. ## What you expected -`robots.txt` lists both sitemaps, only production builds load analytics, and deploy previews carry a `noindex` header. +`robots.txt` lists both sitemaps, only production builds load analytics, and +deploy previews carry a `noindex` header. ## URL @@ -27,6 +37,10 @@ Make these changes in `kubevirt/kubevirt.github.io`: ## Additional context -Related: #9056 adds analytics to the user guide, and #9058 applies the `noindex` change to the guide's `netlify.toml`. +Related: #9056 adds analytics to the user guide, and #9058 applies the `noindex` +change to the guide's `netlify.toml`. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md b/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md index 9817c5e0..a18511e7 100644 --- a/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md +++ b/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md @@ -6,19 +6,31 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -The Netlify build in `netlify.toml` installs unpinned packages with `pip install mkdocs mkdocs-awesome-nav mkdocs-material mkdocs-redirects`. Preview builds can differ from the Prow image build and can break when a package releases. The build command also contains a `sed` line that rewrites `site_url: https://kubevirt.io/docs`. `mkdocs.yml` already sets `site_url` to `https://kubevirt.io/user-guide`, so the line has no effect. Nothing tells search engines to skip preview deploys. +The Netlify build in `netlify.toml` installs unpinned packages with +`pip install mkdocs mkdocs-awesome-nav mkdocs-material mkdocs-redirects`. +Preview builds can differ from the Prow image build and can break when a package +releases. The build command also contains a `sed` line that rewrites +`site_url: https://kubevirt.io/docs`. `mkdocs.yml` already sets `site_url` to +`https://kubevirt.io/user-guide`, so the line has no effect. Nothing tells +search engines to skip preview deploys. Update `netlify.toml` in `kubevirt/user-guide`: 1. Remove the obsolete `sed -i 's|site_url: https://kubevirt.io/docs|...` line. -2. Pin the versions of `mkdocs`, `mkdocs-awesome-nav`, `mkdocs-material`, and `mkdocs-redirects`, or move them to a `requirements.txt` that the build installs. Match the versions in the Prow image used by `kubevirt/project-infra`. -3. Emit `X-Robots-Tag: noindex` for non-production deploys by adding a `_headers` file or `[context.deploy-preview]` and `[context.branch-deploy]` sections. +2. Pin the versions of `mkdocs`, `mkdocs-awesome-nav`, `mkdocs-material`, and + `mkdocs-redirects`, or move them to a `requirements.txt` that the build + installs. Match the versions in the Prow image used by + `kubevirt/project-infra`. +3. Emit `X-Robots-Tag: noindex` for non-production deploys by adding a + `_headers` file or `[context.deploy-preview]` and `[context.branch-deploy]` + sections. Build a preview and confirm the header with `curl -I`. ## What you expected -Preview builds use the same package versions as the Prow image, the build command has no dead lines, and preview deploys return `X-Robots-Tag: noindex`. +Preview builds use the same package versions as the Prow image, the build +command has no dead lines, and preview deploys return `X-Robots-Tag: noindex`. ## URL @@ -28,6 +40,11 @@ Preview builds use the same package versions as the Prow image, the build comman ## Additional context -Related: #9056 also edits the `netlify.toml` build command, and #9057 applies the `noindex` change to the website repository. Ask the maintainers whether the Prow image or Netlify is the source of truth for versions. +Related: #9056 also edits the `netlify.toml` build command, and #9057 applies +the `noindex` change to the website repository. Ask the maintainers whether the +Prow image or Netlify is the source of truth for versions. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9059-unify-search.md b/analyses/2026/kubevirt/issues/9059-unify-search.md index 2af2850a..a70d9ca2 100644 --- a/analyses/2026/kubevirt/issues/9059-unify-search.md +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -6,18 +6,28 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -Readers cannot search the full KubeVirt documentation set from one place. The guide's search covers only the user guide, and the main website search (the lunr index in `_layouts/search.html` of `kubevirt/kubevirt.github.io`) covers only `site.posts`. The API reference and quickstarts are not searchable from either. +Readers cannot search the full KubeVirt documentation set from one place. The +guide's search covers only the user guide, and the main website search (the lunr +index in `_layouts/search.html` of `kubevirt/kubevirt.github.io`) covers only +`site.posts`. The API reference and quickstarts are not searchable from either. Work on this in two steps: -1. Ask the website maintainers whether the API reference and quickstarts can be indexed by the same search as the guide, for example by moving the guide search to a site-wide index. Record the answer in this issue. -2. Implement the quick improvements in `kubevirt/kubevirt.github.io`: extend the lunr index in `_layouts/search.html` to include `site.pages` in addition to `site.posts`, and add a link from the website search page to the guide search (and the other way around). +1. Ask the website maintainers whether the API reference and quickstarts can be + indexed by the same search as the guide, for example by moving the guide + search to a site-wide index. Record the answer in this issue. +2. Implement the quick improvements in `kubevirt/kubevirt.github.io`: extend the + lunr index in `_layouts/search.html` to include `site.pages` in addition to + `site.posts`, and add a link from the website search page to the guide search + (and the other way around). -If the maintainers choose a site-wide index, open a follow-up issue for it with the agreed scope. +If the maintainers choose a site-wide index, open a follow-up issue for it with +the agreed scope. ## What you expected -A reader who starts on either site can find documentation pages from the other, and the maintainers' decision about a single search index is recorded. +A reader who starts on either site can find documentation pages from the other, +and the maintainers' decision about a single search index is recorded. ## URL @@ -27,6 +37,11 @@ A reader who starts on either site can find documentation pages from the other, ## Additional context -Related: #9042 adds an API reference entry to the guide navigation, and #9045 asks whether the two sites should converge on one toolchain, which would simplify search. +Related: #9042 adds an API reference entry to the guide navigation, and #9045 +asks whether the two sites should converge on one toolchain, which would +simplify search. -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). +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). diff --git a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md index 93d32156..3ede2ab4 100644 --- a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -6,21 +6,32 @@ repo: https://github.com/kubevirt/user-guide/issues ## Description -No document names who administers the infrastructure behind the guide and the website. A maintainer who needs Netlify access, a DNS change, an analytics report, or a 404 report has nobody to ask. The site also cannot set a `Strict-Transport-Security` header, because GitHub Pages does not allow custom response headers. +No document names who administers the infrastructure behind the guide and the +website. A maintainer who needs Netlify access, a DNS change, an analytics +report, or a 404 report has nobody to ask. The site also cannot set a +`Strict-Transport-Security` header, because GitHub Pages does not allow custom +response headers. -Add a "Site infrastructure" section to the README of both `kubevirt/user-guide` and `kubevirt/kubevirt.github.io`, or one page in `kubevirt/community` that both READMEs link to. Ask the maintainers who the custodians are, then list for each item the owner and how to request access: +Add a "Site infrastructure" section to the README of both `kubevirt/user-guide` +and `kubevirt/kubevirt.github.io`, or one page in `kubevirt/community` that both +READMEs link to. Ask the maintainers who the custodians are, then list for each +item the owner and how to request access: - The Netlify site. - GitHub Pages and the custom-domain settings. - DNS for kubevirt.io. -- The Adobe Analytics property and Google Search Console, including how to request a 404 report. +- The Adobe Analytics property and Google Search Console, including how to + request a 404 report. - The Prow job definitions in `kubevirt/project-infra`. -Add an HSTS item: ask whether a DNS or CDN provider in front of kubevirt.io can set `Strict-Transport-Security`. If none exists, record the limitation as a known gap. +Add an HSTS item: ask whether a DNS or CDN provider in front of kubevirt.io can +set `Strict-Transport-Security`. If none exists, record the limitation as a +known gap. ## What you expected -A maintainer can read one section and find the owner of every piece of site infrastructure, how to request access, and the known HSTS gap. +A maintainer can read one section and find the owner of every piece of site +infrastructure, how to request access, and the known HSTS gap. ## URL @@ -30,6 +41,11 @@ A maintainer can read one section and find the owner of every piece of site infr ## Additional context -Related: #9041 adds a "Where documentation lives" section to the same READMEs, #9056 and #9057 enable and gate analytics, and #9045 records the toolchain decision. +Related: #9041 adds a "Where documentation lives" section to the same READMEs, +#9056 and #9057 enable and gate analytics, and #9045 records the toolchain +decision. -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). +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). diff --git a/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md index bdb5df68..eacca446 100644 --- a/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md +++ b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md @@ -6,16 +6,24 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -A new user cannot go from a working cluster to a running VirtualMachine without piecing together the Installation, `virtctl`, Basic Use, and Lifecycle pages. The sub-issues below add a single Getting Started page, rewrite Basic Use around VirtualMachine, put the core installation procedure first, and make the commands on those pages easy to copy. Start with the code-copy change, then work the pages in the order a new user reads them. +A new user cannot go from a working cluster to a running VirtualMachine without +piecing together the Installation, `virtctl`, Basic Use, and Lifecycle pages. +The sub-issues below add a single Getting Started page, rewrite Basic Use around +VirtualMachine, put the core installation procedure first, and make the commands +on those pages easy to copy. Start with the code-copy change, then work the +pages in the order a new user reads them. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Enable code copy and search features in mkdocs.yml #9006](9006-enable-code-copy-search.md) -- [Restructure the Installation page around the core procedure #9004](9004-restructure-installation-page.md) -- [Create an Installing virtctl page #9005](9005-create-installing-virtctl-page.md) -- [Add a Getting Started page after Architecture #9001](9001-add-getting-started-page.md) -- [Rewrite Basic Use as "Your first VirtualMachine" #9002](9002-rewrite-basic-use.md) -- [Add a Start here link and fix the Slack link on the Welcome page #9003](9003-fix-welcome-page-links.md) -- [Convert shell code blocks to fenced blocks #9007](9007-convert-shell-code-blocks.md) +- [Enable code copy features #9006](9006-enable-code-copy-search.md) +- [Restructure Install page #9004](9004-restructure-installation-page.md) +- [Create Install virtctl page #9005](9005-create-installing-virtctl-page.md) +- [Add a Getting Started page #9001](9001-add-getting-started-page.md) +- [Rewrite Basic Use #9002](9002-rewrite-basic-use.md) +- [Add a Start here link #9003](9003-fix-welcome-page-links.md) +- [Convert shell code blocks #9007](9007-convert-shell-code-blocks.md) diff --git a/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md index 97a9bf14..3a13a773 100644 --- a/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md +++ b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md @@ -6,16 +6,24 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -Some pages are unreachable from the navigation, the Release Notes sit in the middle of the section list, section headings give no overview, and several page titles name an API instead of a reader goal. The sub-issues below fix the broken navigation first, then add landing pages, rename titles, remove legacy content, and split the longest pages. Most changes touch the same `.nav.yml` files and `mkdocs.yml` redirects, so work them in order to avoid merge conflicts. +Some pages are unreachable from the navigation, the Release Notes sit in the +middle of the section list, section headings give no overview, and several page +titles name an API instead of a reader goal. The sub-issues below fix the broken +navigation first, then add landing pages, rename titles, remove legacy content, +and split the longest pages. Most changes touch the same `.nav.yml` files and +`mkdocs.yml` redirects, so work them in order to avoid merge conflicts. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Fix orphaned pages and Release Notes placement in navigation #9008](9008-fix-navigation-orphans.md) -- [Add an API reference entry to the guide navigation #9042](9042-add-api-reference-link.md) -- [Remove or archive legacy installation content #9011](9011-remove-legacy-installation-content.md) -- [Add landing pages to Compute, Network, and Storage #9009](9009-add-section-landing-pages.md) -- [Rename API-centric titles and group legacy workload pages #9010](9010-rename-api-page-titles.md) -- [Split the Disks and Volumes and Interfaces and Networks pages #9050](9050-split-disks-networks-pages.md) -- [Split the Live Migration and Release Notes pages #9051](9051-split-migration-release-notes.md) +- [Fix orphaned pages and Release Notes #9008](9008-fix-navigation-orphans.md) +- [Add an API reference entry #9042](9042-add-api-reference-link.md) +- [Remove legacy install #9011](9011-remove-legacy-installation-content.md) +- [Add landing pages #9009](9009-add-section-landing-pages.md) +- [Rename API-centric titles #9010](9010-rename-api-page-titles.md) +- [Split the Disks and Volume #9050](9050-split-disks-networks-pages.md) +- [Split the Live Migration #9051](9051-split-migration-release-notes.md) diff --git a/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md index e2a1fc52..3855d0f0 100644 --- a/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md +++ b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md @@ -6,14 +6,22 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -Several v1.9 features appear only in the release notes, the guide has no `virtctl` command reference or feature-gate table, and users have no troubleshooting page. The sub-issues below add the missing feature documentation and the reference and troubleshooting pages readers look for first. The `virtctl` reference and feature-gate table can link to the feature pages, so write those pages first. +Several v1.9 features appear only in the release notes, the guide has no +`virtctl` command reference or feature-gate table, and users have no +troubleshooting page. The sub-issues below add the missing feature documentation +and the reference and troubleshooting pages readers look for first. The +`virtctl` reference and feature-gate table can link to the feature pages, so +write those pages first. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Document the VirtualMachineBackup API #9012](9012-document-virtualmachinebackup-api.md) -- [Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression #9013](9013-document-v19-features.md) +- [Doc VirtualMachineBackup #9012](9012-document-virtualmachinebackup-api.md) +- [Doc CrossArchitectureVirtualization #9013](9013-document-v19-features.md) - [Create a virtctl command reference #9014](9014-create-virtctl-reference.md) - [Add a feature-gate table #9015](9015-add-feature-gate-table.md) -- [Add a user-facing Troubleshooting page #9016](9016-add-troubleshooting-page.md) +- [Add user-facing Troubleshooting #9016](9016-add-troubleshooting-page.md) diff --git a/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md index b8f22bac..d267ea81 100644 --- a/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md +++ b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md @@ -6,12 +6,20 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -Readers cannot tell which KubeVirt version a page describes, and contributors cannot tell how release branches and cherry-picks work. The sub-issues below standardize the feature-state admonition, document the versioning model, and publish versioned documentation with a version selector. Work them in order: the feature-state format helps immediately, the documented model must be confirmed by maintainers before publishing, and the version selector builds on that model. +Readers cannot tell which KubeVirt version a page describes, and contributors +cannot tell how release branches and cherry-picks work. The sub-issues below +standardize the feature-state admonition, document the versioning model, and +publish versioned documentation with a version selector. Work them in order: the +feature-state format helps immediately, the documented model must be confirmed +by maintainers before publishing, and the version selector builds on that model. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Standardize the feature-state admonition #9017](9017-standardize-feature-state-admonition.md) -- [Document the content versioning model, release-notes process, and localization #9018](9018-document-versioning-model.md) -- [Publish versioned documentation with a version selector #9019](9019-publish-versioned-docs.md) +- [Standardize feature #9017](9017-standardize-feature-state-admonition.md) +- [Document the content versioning #9018](9018-document-versioning-model.md) +- [Publish versioned documentation #9019](9019-publish-versioned-docs.md) diff --git a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md index ade898a4..abe867c4 100644 --- a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md +++ b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md @@ -14,7 +14,7 @@ This umbrella issue tracks recommended changes resulting from an analysis of the - [Add a pull request template #9022](9022-add-pull-request-template.md) - [Add a documentation style guide #9021](9021-add-style-guide.md) -- [Expand CONTRIBUTING.md into a documentation contributor guide #9020](9020-expand-contributing-guide.md) +- [Expand CONTRIBUTING.md #9020](9020-expand-contributing-guide.md) - [Add per-directory OWNERS files #9023](9023-add-owners-files.md) -- [Add MAINTAINERS.md and a maintainer ladder #9026](9026-add-maintainers-file.md) -- [Triage open pull requests and add a stale-PR policy #9025](9025-triage-open-prs.md) +- [Add MAINTAINERS.md #9026](9026-add-maintainers-file.md) +- [Triage open pull requests #9025](9025-triage-open-prs.md) diff --git a/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md index 30a8bb57..f080b089 100644 --- a/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md +++ b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md @@ -6,15 +6,22 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -A newcomer who opens the Contributing page finds a list of links but no explanation of how the project is run, where to ask for help, which issues to pick up, or what the first change looks like. The sub-issues below add that context to the page and fix the beginner issue labels and backlog it points to. Standardize the label first so the issue links on the page stay valid. +A newcomer who opens the Contributing page finds a list of links but no +explanation of how the project is run, where to ask for help, which issues to +pick up, or what the first change looks like. The sub-issues below add that +context to the page and fix the beginner issue labels and backlog it points to. +Standardize the label first so the issue links on the page stay valid. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Standardize the good first issue label #9038](9038-standardize-good-first-issue.md) -- [Add a project overview and resource descriptions to the Contributing page #9034](9034-add-contributing-overview.md) -- [Link filtered issue lists and explain labels on the Contributing page #9036](9036-link-issue-lists.md) -- [Add where-to-ask-help and the VEP docs deadline to the Contributing page #9035](9035-add-help-and-vep-guidance.md) -- [Add a first documentation change walkthrough to the Contributing page #9037](9037-add-first-change-walkthrough.md) -- [Triage the issue backlog and publish a triage cadence #9039](9039-triage-issue-backlog.md) +- [Standardize the good first issue #9038](9038-standardize-good-first-issue.md) +- [Add a project overview #9034](9034-add-contributing-overview.md) +- [Link filtered issue lists #9036](9036-link-issue-lists.md) +- [Add where-to-ask-help #9035](9035-add-help-and-vep-guidance.md) +- [Add a first documentation #9037](9037-add-first-change-walkthrough.md) +- [Triage the issue backlog #9039](9039-triage-issue-backlog.md) diff --git a/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md index 63054e4f..3af28e0d 100644 --- a/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md +++ b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md @@ -6,14 +6,22 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -Readers who stay in the user guide cannot find the project's Slack channels, mailing list, meetings, governance documents, or a home for documentation work. The sub-issues below put repository and social links on every page, add a Community and communication page, link the community from the guide, explain how the project is governed, and give documentation a SIG home. Add the footer links first because they are a one-file change. +Readers who stay in the user guide cannot find the project's Slack channels, +mailing list, meetings, governance documents, or a home for documentation work. +The sub-issues below put repository and social links on every page, add a +Community and communication page, link the community from the guide, explain how +the project is governed, and give documentation a SIG home. Add the footer links +first because they are a one-file change. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Add repository and social links to the footer #9032](9032-add-footer-social-links.md) -- [Add a Community and communication page to the guide #9030](9030-add-community-page.md) -- [Add a Community and adoption block to the index and Contributing page #9031](9031-add-community-adoption-links.md) -- [Add a Governance section to the kubevirt.io Community page #9040](9040-add-governance-section.md) -- [Give documentation a SIG home and clarify SIG meeting mechanics #9024](9024-give-docs-sig-home.md) +- [Add repository and social links #9032](9032-add-footer-social-links.md) +- [Add a Community and communication page #9030](9030-add-community-page.md) +- [Add a Community and adoption block #9031](9031-add-community-adoption-links.md) +- [Add a Governance section #9040](9040-add-governance-section.md) +- [Give documentation a SIG home #9024](9024-give-docs-sig-home.md) diff --git a/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md index fc2a91ba..de59839c 100644 --- a/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md +++ b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md @@ -6,12 +6,19 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -The guide links to a legacy `master` branch path, uses `master` as an example node name, and relies on minimizing words such as "simply" and "easily". The sub-issues below fix the legacy references, reword the prose, and add an automated check so new occurrences are caught in pull requests. Fix the legacy references first because they are small and exact. +The guide links to a legacy `master` branch path, uses `master` as an example +node name, and relies on minimizing words such as "simply" and "easily". The +sub-issues below fix the legacy references, reword the prose, and add an +automated check so new occurrences are caught in pull requests. Fix the legacy +references first because they are small and exact. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Fix legacy master links and the node-name example #9029](9029-fix-legacy-master-references.md) -- [Reword minimizing language and cancel terminology #9027](9027-reword-minimizing-language.md) -- [Add accessibility and language checks to CI #9028](9028-add-ci-doc-checks.md) +- [Fix legacy master links #9029](9029-fix-legacy-master-references.md) +- [Reword minimizing language #9027](9027-reword-minimizing-language.md) +- [Add accessibility #9028](9028-add-ci-doc-checks.md) diff --git a/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md index c89fbd63..a9d826c6 100644 --- a/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md +++ b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md @@ -6,13 +6,21 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -The guide's header and link colors have low contrast, the logo has no useful alt text, wide tables and the Architecture diagram do not work well on mobile or with screen readers, and the guide's brand colors differ from the main site. The sub-issues below fix these problems and record the brand values so both sites stay aligned. Fix the logo and unused assets first, then the contrast and mobile issues, then publish the brand reference. +The guide's header and link colors have low contrast, the logo has no useful alt +text, wide tables and the Architecture diagram do not work well on mobile or +with screen readers, and the guide's brand colors differ from the main site. The +sub-issues below fix these problems and record the brand values so both sites +stay aligned. Fix the logo and unused assets first, then the contrast and mobile +issues, then publish the brand reference. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Fix logo alt text and remove unused assets and config #9033](9033-fix-logo-and-unused-assets.md) -- [Fix mobile tables and replace the Architecture diagram #9049](9049-fix-mobile-tables.md) -- [Fix header and link contrast and align brand colors #9048](9048-fix-contrast-and-colors.md) +- [Fix logo alt text #9033](9033-fix-logo-and-unused-assets.md) +- [Fix mobile tables #9049](9049-fix-mobile-tables.md) +- [Fix header and link contrast #9048](9048-fix-contrast-and-colors.md) - [Publish a brand reference #9052](9052-publish-brand-reference.md) diff --git a/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md index 54fdbf77..3eafd4f6 100644 --- a/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md +++ b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md @@ -6,14 +6,21 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -The user guide and kubevirt.io footers do not meet the CNCF project website requirements, the website lacks community health files, and the site shows adopter logos without case studies or use cases. The sub-issues below fix the footers and health files, then add the adopters page, adopter use cases, and blog categories. Fix the footers first because they are compliance items. +The user guide and kubevirt.io footers do not meet the CNCF project website +requirements, the website lacks community health files, and the site shows +adopter logos without case studies or use cases. The sub-issues below fix the +footers and health files, then add the adopters page, adopter use cases, and +blog categories. Fix the footers first because they are compliance items. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Fix the website footer and add community health files #9047](9047-fix-website-footer.md) -- [Bring the user guide footer into compliance #9046](9046-fix-guide-footer.md) -- [Add an adopters page and link CNCF case studies #9053](9053-add-adopters-page.md) -- [Show adopter use cases and KubeVirt-specific vendor links #9054](9054-show-adopter-use-cases.md) +- [Fix the website footer #9047](9047-fix-website-footer.md) +- [Bring user guide footer into compliance #9046](9046-fix-guide-footer.md) +- [Add an adopters page 9053](9053-add-adopters-page.md) +- [Show adopter use cases #9054](9054-show-adopter-use-cases.md) - [Add blog categories and tags #9055](9055-add-blog-categories.md) diff --git a/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md index 12326559..7cd9a022 100644 --- a/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md +++ b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md @@ -6,13 +6,21 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -The user guide collects no analytics, preview deploys can be indexed and pollute analytics on the main site, `robots.txt` points at the wrong sitemap, and search covers only part of the documentation. The sub-issues below fix the indexing and build configuration first, then enable production-only analytics, and finally unify search. Work the configuration fixes first so analytics data is clean from the start. +The user guide collects no analytics, preview deploys can be indexed and pollute +analytics on the main site, `robots.txt` points at the wrong sitemap, and search +covers only part of the documentation. The sub-issues below fix the indexing and +build configuration first, then enable production-only analytics, and finally +unify search. Work the configuration fixes first so analytics data is clean from +the start. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Make guide preview builds reproducible and non-indexable #9058](9058-fix-guide-preview-builds.md) -- [Fix robots.txt and gate analytics on kubevirt.io #9057](9057-fix-robots-and-site-analytics.md) -- [Enable production-only analytics and a 404 report on the user guide #9056](9056-enable-guide-analytics.md) -- [Unify search across the guide and the website #9059](9059-unify-search.md) +- [Make guide preview builds reproducible #9058](9058-fix-guide-preview-builds.md) +- [Fix robots.txt #9057](9057-fix-robots-and-site-analytics.md) +- [Enable production-only analytics #9056](9056-enable-guide-analytics.md) +- [Unify search across the guide #9059](9059-unify-search.md) diff --git a/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md index 5975b0b6..2bbd3304 100644 --- a/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md +++ b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md @@ -6,14 +6,23 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -Documentation is spread across the user guide, kubevirt.io, `kubevirt/kubevirt/docs`, and the CDI repository without a stated boundary, and no one document records who administers the site infrastructure. The sub-issues below document where documentation lives and who owns the infrastructure, decide whether the website and guide should converge, and audit the other repositories for user-facing content. Record the boundary and ownership first; the audits and the toolchain decision depend on them. +Documentation is spread across the user guide, kubevirt.io, +`kubevirt/kubevirt/docs`, and the CDI repository without a stated boundary, and +no one document records who administers the site infrastructure. The sub-issues +below document where documentation lives and who owns the infrastructure, decide +whether the website and guide should converge, and audit the other repositories +for user-facing content. Record the boundary and ownership first; the audits and +the toolchain decision depend on them. -This umbrella 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). +This umbrella 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). ## Sub-issues -- [Document where documentation lives #9041](9041-document-content-boundary.md) -- [Document site infrastructure ownership #9060](9060-document-site-infrastructure.md) -- [Decide whether to converge the website and user guide #9045](9045-decide-converge-toolchains.md) -- [Audit kubevirt/kubevirt docs for user-facing content #9043](9043-audit-kubevirt-docs.md) -- [Audit CDI documentation for storage pages #9044](9044-audit-cdi-docs.md) +- [Doc where documentation lives #9041](9041-document-content-boundary.md) +- [Doc site infrastructure #9060](9060-document-site-infrastructure.md) +- [Decide whether to converge #9045](9045-decide-converge-toolchains.md) +- [Audit kubevirt/kubevirt docs #9043](9043-audit-kubevirt-docs.md) +- [Audit CDI documentation #9044](9044-audit-cdi-docs.md) From ed2a1ce732be269a55fb251a9878be9d05f8c385 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 08:54:52 -0700 Subject: [PATCH 08/31] format fixes Signed-off-by: Bruce Hamilton --- .cspell.yml | 4 ++++ analyses/2026/kubevirt/issues-coverage.md | 9 ++++++-- .../issues/9010-rename-api-page-titles.md | 23 ++++++++++--------- .../issues/9034-add-contributing-overview.md | 4 ++-- .../kubevirt/issues/9036-link-issue-lists.md | 2 +- .../issues/9052-publish-brand-reference.md | 4 ++-- .../9060-document-site-infrastructure.md | 12 ++++++---- .../issues/U-9065-build-contributor-guide.md | 11 +++++++-- 8 files changed, 44 insertions(+), 25 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 052d623f..b5735713 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -101,3 +101,7 @@ words: - kubevirt - viewports - rniw + - zstd + - vmexport + - numa + - uefi diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 30a97584..7f017977 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -1,8 +1,13 @@ # 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 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. +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 diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index a5920261..a809c1a4 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -12,16 +12,15 @@ the User Workloads "Workloads" group mixes current and legacy mechanisms. Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: -| Current title | Proposed title | -| ------------------------------------------------------------- | ------------------------------------------------ | -| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | -| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | -| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | -| Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | +Current title (path under `docs/storage`) Proposed title: -Choose the last title after reading the page; ask the maintainers if the purpose -is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update -inbound links. +(`clone_api.md`): Cloning VMs (`export_api.md`): Exporting VMs and volumes +(`snapshot_restore_api.md`): Snapshotting and restoring VMs +(`migration_controller.md`): A title that states what is accomplished + +Choose the last title after reading the page; ask the maintainers if the +purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` +and update inbound links. Then reorder the "Workloads" group in `docs/user_workloads/.nav.yml`. List current mechanisms (instance types, VirtualMachine Templates, pools) first. @@ -47,7 +46,9 @@ current mechanisms while legacy pages are labeled as such. Prefer keeping file names unchanged to avoid broken inbound links, unless the rename adds clear value. -This issue tracks recommended changes resulting from an analysis of the KubeVirt -documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +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). diff --git a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md index 88a386a7..b2a4621f 100644 --- a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -37,8 +37,8 @@ link states what it leads to. Related: #9035, #9036, and #9037 (other additions to the same page; coordinate to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 (governance text on the Community page, which should use the same wording), and -#9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list -should the page link, the community one or a user guide one? +issue #9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers +list should the page link, the community one or a user guide one? This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md index d4cb58dc..f953af97 100644 --- a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -37,7 +37,7 @@ beginner-friendly issues, and knows what each label means. Depends on #9038 (the label name must be standardized before linking the filter) and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, -#9037. +and #9037. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md index 79ad54e8..bf94d0ec 100644 --- a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -37,8 +37,8 @@ stylesheet points to it. ## Additional context -Related: #9048 aligns the guide's primary color with the website scale, and -#9033 fixes the logo alt text. Complete #9048 first so the reference lists the +Related: #9048 aligns the guide's primary color with the website scale, +and #9033 fixes the logo alt text. Complete #9048 first so the reference lists the final values. This issue tracks recommended changes resulting from an analysis of the KubeVirt diff --git a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md index 3ede2ab4..bc73c9d9 100644 --- a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -41,11 +41,13 @@ infrastructure, how to request access, and the known HSTS gap. ## Additional context -Related: #9041 adds a "Where documentation lives" section to the same READMEs, -#9056 and #9057 enable and gate analytics, and #9045 records the toolchain -decision. +Related: #9041 adds a "Where documentation lives" section to the same +READMEs, #9056 and #9057 enable and gate analytics, and #9045 records the +toolchain decision. + +This issue tracks recommended changes resulting from an analysis of the +KubeVirt documentation commissioned by +[CNCF](https://www.cncf.io/projects/kubevirt/). -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). diff --git a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md index abe867c4..7e951097 100644 --- a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md +++ b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md @@ -6,9 +6,16 @@ repo: https://github.com/kubevirt/user-guide/issues ## Umbrella Issue -`CONTRIBUTING.md` is a pointer, and the repository has no pull request template, style guide, per-area reviewers, or stale-PR policy. The sub-issues below give contributors the guidance and tooling they need to propose, write, and review a documentation change. Start with the pull request template and style guide, which are quick wins, then expand the contributor guide that links to them. +`CONTRIBUTING.md` is a pointer, and the repository has no pull request template, +style guide, per-area reviewers, or stale-PR policy. The sub-issues below give +contributors the guidance and tooling they need to propose, write, and review a +documentation change. Start with the pull request template and style guide, +which are quick wins, then expand the contributor guide that links to them. -This umbrella 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). +This umbrella 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). ## Sub-issues From a836ddb8e82d3a2f0f50b3437253aa62cfee1c93 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 12:53:13 -0700 Subject: [PATCH 09/31] format fixes/test Signed-off-by: Bruce Hamilton --- .../kubevirt/issues/9010-rename-api-page-titles.md | 13 +++++++++---- .../kubevirt/issues/9052-publish-brand-reference.md | 6 +++--- .../issues/9060-document-site-infrastructure.md | 9 ++++----- 3 files changed, 16 insertions(+), 12 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index a809c1a4..f03784d1 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -12,11 +12,16 @@ the User Workloads "Workloads" group mixes current and legacy mechanisms. Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: -Current title (path under `docs/storage`) Proposed title: + -(`clone_api.md`): Cloning VMs (`export_api.md`): Exporting VMs and volumes -(`snapshot_restore_api.md`): Snapshotting and restoring VMs -(`migration_controller.md`): A title that states what is accomplished +| Current title | Proposed title | +| --- | --- | +| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | +| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | +| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | +| Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | + + Choose the last title after reading the page; ask the maintainers if the purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md index bf94d0ec..f097624e 100644 --- a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -37,9 +37,9 @@ stylesheet points to it. ## Additional context -Related: #9048 aligns the guide's primary color with the website scale, -and #9033 fixes the logo alt text. Complete #9048 first so the reference lists the -final values. +Related: #9048 aligns the guide's primary color with the website scale, and +issue #9033 fixes the logo alt text. Complete #9048 first so the reference lists +the final values. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md index bc73c9d9..ee6cff33 100644 --- a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -41,13 +41,12 @@ infrastructure, how to request access, and the known HSTS gap. ## Additional context -Related: #9041 adds a "Where documentation lives" section to the same -READMEs, #9056 and #9057 enable and gate analytics, and #9045 records the +Related: #9041 adds a "Where documentation lives" section to the same READMEs, +issues #9056 and #9057 enable and gate analytics, and #9045 records the toolchain decision. -This issue tracks recommended changes resulting from an analysis of the -KubeVirt documentation commissioned by -[CNCF](https://www.cncf.io/projects/kubevirt/). +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). From f170589dc9646f883cab8f619040e71d60f36599 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 13:02:18 -0700 Subject: [PATCH 10/31] formatting Signed-off-by: Bruce Hamilton --- .../issues/9010-rename-api-page-titles.md | 21 +++++++++---------- .../issues/9035-add-help-and-vep-guidance.md | 2 +- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index f03784d1..72a5de72 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -14,18 +14,18 @@ entry: -| Current title | Proposed title | -| --- | --- | -| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | -| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | -| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | +| Current title | Proposed title | +| ------------------------------------------------------------- | ------------------------------------------------ | +| Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | +| Export API (`docs/storage/export_api.md`) | Exporting VirtualMachines and volumes | +| Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | | Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | -Choose the last title after reading the page; ask the maintainers if the -purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` -and update inbound links. +Choose the last title after reading the page; ask the maintainers if the purpose +is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update +inbound links. Then reorder the "Workloads" group in `docs/user_workloads/.nav.yml`. List current mechanisms (instance types, VirtualMachine Templates, pools) first. @@ -51,9 +51,8 @@ current mechanisms while legacy pages are labeled as such. Prefer keeping file names unchanged to avoid broken inbound links, unless the rename adds clear value. -This issue tracks recommended changes resulting from an analysis of the -KubeVirt documentation commissioned by -[CNCF](https://www.cncf.io/projects/kubevirt/). +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). diff --git a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md index ed4801fd..01375328 100644 --- a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -38,7 +38,7 @@ first-time contributors exist, or could one be offered? If not, remove the mentoring note. Who is the docs contact? Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), -#9034, #9036, #9037 (same page), and #9020. +and #9034, #9036, #9037 (same page), and #9020. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). From 44c730a684f1a1c72bdf5c8cd37afdcb1c6bd9e0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 13:45:15 -0700 Subject: [PATCH 11/31] link fixes Signed-off-by: Bruce Hamilton --- .../2026/kubevirt/issues/9009-add-section-landing-pages.md | 3 --- analyses/2026/kubevirt/issues/9023-add-owners-files.md | 7 ++++--- .../2026/kubevirt/issues/9054-show-adopter-use-cases.md | 1 - analyses/2026/kubevirt/issues/9059-unify-search.md | 1 - 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md index ee79d332..9a93043d 100644 --- a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -32,9 +32,6 @@ page for each common task. ## URL -- https://kubevirt.io/user-guide/compute/ -- https://kubevirt.io/user-guide/network/ -- https://kubevirt.io/user-guide/storage/ - New files `docs/compute/index.md`, `docs/network/index.md`, `docs/storage/index.md`; the existing `.nav.yml` files in each directory diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 0e979550..20b22b94 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -34,9 +34,10 @@ experts, while root approvers still approve site-wide changes. - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root - New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` -- Guide sections: https://kubevirt.io/user-guide/network/, - https://kubevirt.io/user-guide/storage/, - https://kubevirt.io/user-guide/compute/ +- Guide sections: + [https://kubevirt.io/user-guide/compute/] + [https://kubevirt.io/user-guide/network/] + [https://kubevirt.io/user-guide/storage/] ## Additional context diff --git a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md index b4588d4e..49e068a9 100644 --- a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -35,7 +35,6 @@ mention KubeVirt. - https://kubevirt.io/ (End Users and Vendors logo walls) - https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/adopters.yml -- https://github.com/kubevirt/kubevirt.github.io/blob/main/ADOPTERS.md ## Additional context diff --git a/analyses/2026/kubevirt/issues/9059-unify-search.md b/analyses/2026/kubevirt/issues/9059-unify-search.md index a70d9ca2..83724482 100644 --- a/analyses/2026/kubevirt/issues/9059-unify-search.md +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -32,7 +32,6 @@ and the maintainers' decision about a single search index is recorded. ## URL - https://kubevirt.io/user-guide/ (search box) -- https://kubevirt.io/search/ - https://github.com/kubevirt/kubevirt.github.io/blob/main/_layouts/search.html ## Additional context From eae64d087e79db5913836de9de869d99c85550d0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:01:25 -0700 Subject: [PATCH 12/31] link fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/9023-add-owners-files.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 20b22b94..2ff05839 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -35,9 +35,9 @@ experts, while root approvers still approve site-wide changes. - `OWNERS` and `OWNERS_ALIASES` in the repository root - New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` - Guide sections: - [https://kubevirt.io/user-guide/compute/] - [https://kubevirt.io/user-guide/network/] - [https://kubevirt.io/user-guide/storage/] + `https://kubevirt.io/user-guide/compute/` + `https://kubevirt.io/user-guide/network/` + `https://kubevirt.io/user-guide/storage/` ## Additional context From b63f352dc493cb76412146210f3388b55755606f Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:16:38 -0700 Subject: [PATCH 13/31] format fixing Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/9023-add-owners-files.md | 2 +- analyses/2026/kubevirt/issues/9026-add-maintainers-file.md | 2 +- .../2026/kubevirt/issues/9041-document-content-boundary.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 2ff05839..003ce969 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -34,7 +34,7 @@ experts, while root approvers still approve site-wide changes. - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root - New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` -- Guide sections: +- Guide sections: `https://kubevirt.io/user-guide/compute/` `https://kubevirt.io/user-guide/network/` `https://kubevirt.io/user-guide/storage/` diff --git a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md index 940bd7b8..7de043ba 100644 --- a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -36,7 +36,7 @@ the role, and can trust that the approver list reflects active people. - Contributing page: https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) - kubevirt/community membership policy: - https://github.com/kubevirt/community/blob/main/membership_policy.md + `https://github.com/kubevirt/community/blob/main/membership_policy.md` ## Additional context diff --git a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md index 8ee1150a..8fe1bbe2 100644 --- a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md +++ b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md @@ -36,9 +36,9 @@ guidance. ## URL - https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) -- https://github.com/kubevirt/user-guide/blob/main/README.md -- https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md -- https://github.com/kubevirt/kubevirt/blob/main/README.md +- `https://github.com/kubevirt/user-guide/blob/main/README.md` +- `https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md` +- `https://github.com/kubevirt/kubevirt/blob/main/README.md` ## Additional context From 2bf90f679daca4e284eb6ece80bf46355a2bf330 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:23:41 -0700 Subject: [PATCH 14/31] additional format fix Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/9026-add-maintainers-file.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md index 7de043ba..72b17d60 100644 --- a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -34,9 +34,9 @@ the role, and can trust that the approver list reflects active people. - Repository: https://github.com/kubevirt/user-guide (`OWNERS`, `OWNERS_ALIASES`, README) - Contributing page: https://kubevirt.io/user-guide/contributing/ - (`docs/contributing.md`) + - (`docs/contributing.md`) - kubevirt/community membership policy: - `https://github.com/kubevirt/community/blob/main/membership_policy.md` + - (`https://github.com/kubevirt/community/blob/main/membership_policy.md`) ## Additional context From f77c84c78990b9c01133144363591fa85ab3c0b5 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:28:46 -0700 Subject: [PATCH 15/31] minor edit Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/9023-add-owners-files.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 003ce969..4a582afd 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -33,11 +33,9 @@ experts, while root approvers still approve site-wide changes. - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root -- New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` -- Guide sections: - `https://kubevirt.io/user-guide/compute/` - `https://kubevirt.io/user-guide/network/` - `https://kubevirt.io/user-guide/storage/` +- New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, and + `docs/compute/OWNERS`. +- Guide sections in compute, network, and storage. ## Additional context From f74e2771898e1f4d109bfba52b1c9ffcc535f3e1 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:39:35 -0700 Subject: [PATCH 16/31] restored issues-coverage.md full tables Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 250 +++++++++++++++++++++- 1 file changed, 246 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 7f017977..9c840414 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -1,13 +1,255 @@ # Issue coverage report -This report maps every recommendation in +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. +## Issues + + + +| Issue | Title | Label | File | +|---|---|---|---| +| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | +| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | +| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | +| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | +| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | +| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | +| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | +| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | +| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | +| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | +| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | +| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | +| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | +| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | +| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | +| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | +| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | +| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | +| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | +| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | +| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | +| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | +| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | +| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | +| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | +| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | +| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | +| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | +| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | +| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | +| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | +| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | +| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | +| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | +| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | +| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | +| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | +| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | +| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | +| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | +| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | +| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | +| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | +| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | +| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | +| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | +| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | +| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | +| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | +| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | +| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | +| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | +| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | +| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | +| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | +| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | +| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | +| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | +| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | +| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | +| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | +| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | +| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | +| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | +| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | +| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | +| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | +| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | +| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | +| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | +| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | + +## Umbrella issues + +| Umbrella | Label | Sub-issues | +|---|---|---| +| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | +| #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | +| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | +| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | +| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | +| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | +| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | +| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | +| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | +| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | +| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | +| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | + +Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. + +## Recommendation mapping + +| # | Section | Area | CSV priority | Issue(s) | +|---|---|---|---|---| +| 1 | Project Documentation | Information architecture | 2 - High | #9001 | +| 2 | Project Documentation | Information architecture | 2 - High | #9002 | +| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | +| 5 | Project Documentation | Information architecture | 2 - High | #9014 | +| 6 | Project Documentation | Information architecture | 2 - High | #9015 | +| 7 | Project Documentation | Information architecture | 2 - High | #9016 | +| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | +| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 11 | Project Documentation | Information architecture | 2 - High | #9011 | +| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 14 | Project Documentation | New user content | 2 - High | #9001 | +| 15 | Project Documentation | New user content | 2 - High | #9004 | +| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | +| 17 | Project Documentation | New user content | 2 - High | #9004 | +| 18 | Project Documentation | New user content | 2 - High | #9005 | +| 19 | Project Documentation | New user content | 2 - High | #9002 | +| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | +| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | +| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | +| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | +| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | +| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | +| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | +| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | +| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | +| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | +| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | +| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | +| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | +| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | +| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | +| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | + +## Priority adjustments + +No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: + +| Issue | Label | Recommendations raised (original ranking) | Reason | +|---|---|---|---| +| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | +| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | +| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | +| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | +| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | +| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | +| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | +| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | +| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | +| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | +| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | +| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | +| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | +| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | +| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | +| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | +| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | +| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | +| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | + + ## Counts From 1f5571dfaa63e8586a322e593c5249b3ecc5db23 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 14:59:46 -0700 Subject: [PATCH 17/31] table fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 9c840414..33494b39 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -1,6 +1,6 @@ # Issue coverage report -This report maps every recommendation in +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. @@ -10,7 +10,7 @@ uploaded as an issue. | Issue | Title | Label | File | -|---|---|---|---| +| --- | --- | --- | --- | | #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | | #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | | #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | @@ -87,7 +87,7 @@ uploaded as an issue. ## Umbrella issues | Umbrella | Label | Sub-issues | -|---|---|---| +| --- | --- | --- | | #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | | #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | | #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | @@ -106,7 +106,7 @@ Standalone issues outside any umbrella: none. Each umbrella takes the highest la ## Recommendation mapping | # | Section | Area | CSV priority | Issue(s) | -|---|---|---|---|---| +| --- | --- | --- | --- | --- | | 1 | Project Documentation | Information architecture | 2 - High | #9001 | | 2 | Project Documentation | Information architecture | 2 - High | #9002 | | 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | @@ -227,7 +227,7 @@ Standalone issues outside any umbrella: none. Each umbrella takes the highest la No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: | Issue | Label | Recommendations raised (original ranking) | Reason | -|---|---|---|---| +| --- | --- | --- | --- | | #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | | #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | | #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | From aa20c27cdc00f50ab34cdf20d7d5a1ceaa22fb53 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:31:29 -0700 Subject: [PATCH 18/31] fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 93 +++++++++++++---------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 33494b39..8c2c047c 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -22,7 +22,7 @@ uploaded as an issue. | #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | | #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | | #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | -| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtual-machine-backup-api.md` | | #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | | #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | | #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | @@ -84,27 +84,36 @@ uploaded as an issue. | #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | | #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | + + ## Umbrella issues -| Umbrella | Label | Sub-issues | -| --- | --- | --- | -| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | + + +| Umbrella | Label | Sub-issues | +| ----------------------------------------------------------------- | ------ | ----------------------------------------------- | +| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | | #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | -| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | -| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | -| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | -| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | -| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | -| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | -| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | -| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | -| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | -| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | +| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | +| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | +| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | +| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | +| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | +| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | +| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | +| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | +| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | +| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | + + -Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. +Standalone issues outside any umbrella: none. Each umbrella takes the highest +label among its sub-issues. ## Recommendation mapping + + | # | Section | Area | CSV priority | Issue(s) | | --- | --- | --- | --- | --- | | 1 | Project Documentation | Information architecture | 2 - High | #9001 | @@ -220,34 +229,40 @@ Standalone issues outside any umbrella: none. Each umbrella takes the highest la | 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | | 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | | 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | + + | ## Priority adjustments -No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: +No issue takes a label lower than its highest-ranked recommendation. Each issue +takes the highest ranking among its recommendations, so these recommendations +were raised by bundling with higher-ranked work on the same pages or files: -| Issue | Label | Recommendations raised (original ranking) | Reason | -| --- | --- | --- | --- | -| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | -| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | -| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | -| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | -| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | -| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | -| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | -| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | -| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | -| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | -| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | -| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | -| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | -| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | -| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | -| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | -| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | -| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | -| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | -| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | + + +| Issue | Label | Recommendations raised (original ranking) | Reason | +| ----- | ------ | ----------------------------------------- | --------------------------------------------------------------------------- | +| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | +| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | +| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | +| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | +| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | +| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | +| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | +| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | +| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | +| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | +| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | +| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | +| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | +| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | +| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | +| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | +| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | +| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | +| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | From 26ac155e66628a728f69ffbe422e5d7556ec8edd Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:36:40 -0700 Subject: [PATCH 19/31] small nits Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 8c2c047c..dac3fe0a 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -229,9 +229,9 @@ label among its sub-issues. | 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | | 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | | 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | - | + ## Priority adjustments From 95a3132aee515eec8563838f0bf55dc26694fb1a Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:41:30 -0700 Subject: [PATCH 20/31] test partial Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 180 ---------------------- 1 file changed, 180 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index dac3fe0a..1b4450b2 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -86,186 +86,6 @@ uploaded as an issue. -## Umbrella issues - - - -| Umbrella | Label | Sub-issues | -| ----------------------------------------------------------------- | ------ | ----------------------------------------------- | -| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | -| #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | -| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | -| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | -| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | -| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | -| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | -| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | -| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | -| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | -| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | -| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | - - - -Standalone issues outside any umbrella: none. Each umbrella takes the highest -label among its sub-issues. - -## Recommendation mapping - - - -| # | Section | Area | CSV priority | Issue(s) | -| --- | --- | --- | --- | --- | -| 1 | Project Documentation | Information architecture | 2 - High | #9001 | -| 2 | Project Documentation | Information architecture | 2 - High | #9002 | -| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | -| 5 | Project Documentation | Information architecture | 2 - High | #9014 | -| 6 | Project Documentation | Information architecture | 2 - High | #9015 | -| 7 | Project Documentation | Information architecture | 2 - High | #9016 | -| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | -| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 11 | Project Documentation | Information architecture | 2 - High | #9011 | -| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 14 | Project Documentation | New user content | 2 - High | #9001 | -| 15 | Project Documentation | New user content | 2 - High | #9004 | -| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | -| 17 | Project Documentation | New user content | 2 - High | #9004 | -| 18 | Project Documentation | New user content | 2 - High | #9005 | -| 19 | Project Documentation | New user content | 2 - High | #9002 | -| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | -| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | -| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | -| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | -| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | -| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | -| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | -| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | -| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | -| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | -| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | -| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | -| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | -| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | -| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | -| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | -| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | -| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | -| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | -| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | -| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | -| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | -| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | -| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | -| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | -| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | -| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | -| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | -| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | -| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | -| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | -| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | -| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | -| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | -| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | -| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | -| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | -| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | -| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | -| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | -| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | -| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | -| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | -| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | -| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | -| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | -| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | -| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | -| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | -| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | -| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | -| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | -| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | -| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | -| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | -| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | -| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | -| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | -| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | -| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | -| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | -| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | -| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | -| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | -| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | -| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | -| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | -| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | -| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | -| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | -| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | -| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | -| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | -| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | -| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | - - - -## Priority adjustments - -No issue takes a label lower than its highest-ranked recommendation. Each issue -takes the highest ranking among its recommendations, so these recommendations -were raised by bundling with higher-ranked work on the same pages or files: - - - -| Issue | Label | Recommendations raised (original ranking) | Reason | -| ----- | ------ | ----------------------------------------- | --------------------------------------------------------------------------- | -| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | -| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | -| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | -| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | -| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | -| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | -| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | -| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | -| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | -| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | -| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | -| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | -| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | -| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | -| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | -| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | -| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | -| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | -| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | -| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | - - - ## Counts - Recommendations: 114 From 1f8f12751e8bbdae89aae61d9240db1e313bf64c Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:45:17 -0700 Subject: [PATCH 21/31] test 2 Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 1b4450b2..17a0fde7 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -8,7 +8,6 @@ uploaded as an issue. ## Issues - | Issue | Title | Label | File | | --- | --- | --- | --- | | #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | @@ -83,7 +82,6 @@ uploaded as an issue. | #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | | #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | | #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | - ## Counts From 5d6fcca586a0181e5204e4dbb87f27e981a914db Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:50:52 -0700 Subject: [PATCH 22/31] test 3 Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 70 ----------------------- 1 file changed, 70 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 17a0fde7..f9f80c1d 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -12,76 +12,6 @@ uploaded as an issue. | --- | --- | --- | --- | | #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | | #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | -| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | -| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | -| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | -| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | -| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | -| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | -| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | -| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | -| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | -| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtual-machine-backup-api.md` | -| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | -| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | -| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | -| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | -| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | -| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | -| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | -| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | -| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | -| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | -| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | -| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | -| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | -| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | -| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | -| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | -| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | -| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | -| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | -| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | -| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | -| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | -| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | -| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | -| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | -| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | -| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | -| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | -| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | -| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | -| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | -| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | -| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | -| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | -| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | -| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | -| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | -| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | -| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | -| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | -| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | -| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | -| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | -| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | -| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | -| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | -| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | -| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | -| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | -| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | -| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | -| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | -| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | -| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | -| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | -| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | -| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | -| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | -| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | -| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | ## Counts From 0ca15c2f26af6d21d45c8b2a052314d38320a3f2 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 15:55:23 -0700 Subject: [PATCH 23/31] test 4 Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index f9f80c1d..19a7b731 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -8,10 +8,12 @@ uploaded as an issue. ## Issues -| Issue | Title | Label | File | -| --- | --- | --- | --- | -| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | -| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | + +| Issue | Title | Label | File | +| ----- | ------------------------------------------------ | ----- | ---------------------------------- | +| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | +| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | + ## Counts From 4aecf76487c6e4499ad28dff5d4ce80927fca849 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 19:08:01 -0700 Subject: [PATCH 24/31] tables Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 248 ++++++++++++++++++++++ 1 file changed, 248 insertions(+) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 19a7b731..84ce69dc 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -13,6 +13,254 @@ uploaded as an issue. | ----- | ------------------------------------------------ | ----- | ---------------------------------- | | #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | | #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | +| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | +| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | +| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | +| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | +| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | +| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | +| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | +| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | +| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | +| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | +| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | +| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | +| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | +| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | +| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | +| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | +| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | +| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | +| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | +| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | +| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | +| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | +| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | +| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | +| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | +| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | +| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | +| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | +| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | +| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | +| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | +| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | +| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | +| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | +| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | +| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | +| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | +| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | +| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | +| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | +| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | +| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | +| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | +| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | +| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | +| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | +| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | +| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | +| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | +| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | +| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | +| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | +| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | +| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | +| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | +| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | +| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | +| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | +| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | +| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | +| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | +| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | +| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | +| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | +| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | +| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | +| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | +| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | +| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | + + + +## Umbrella issues + + + +| Umbrella | Label | Sub-issues | +| --- | --- | --- | +| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | +| #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | +| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | +| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | +| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | +| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | +| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | +| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | +| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | +| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | +| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | +| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | + + + +Standalone issues outside any umbrella: none. Each umbrella takes the highest +label among its sub-issues. + +## Recommendation mapping + + + +| # | Section | Area | CSV priority | Issue(s) | +| --- | --- | --- | --- | +| 1 | Project Documentation | Information architecture | 2 - High | #9001 | +| 2 | Project Documentation | Information architecture | 2 - High | #9002 | +| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | +| 5 | Project Documentation | Information architecture | 2 - High | #9014 | +| 6 | Project Documentation | Information architecture | 2 - High | #9015 | +| 7 | Project Documentation | Information architecture | 2 - High | #9016 | +| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | +| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 11 | Project Documentation | Information architecture | 2 - High | #9011 | +| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 14 | Project Documentation | New user content | 2 - High | #9001 | +| 15 | Project Documentation | New user content | 2 - High | #9004 | +| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | +| 17 | Project Documentation | New user content | 2 - High | #9004 | +| 18 | Project Documentation | New user content | 2 - High | #9005 | +| 19 | Project Documentation | New user content | 2 - High | #9002 | +| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | +| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | +| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | +| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | +| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | +| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | +| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | +| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | +| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | +| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | +| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | +| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | +| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | +| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | +| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | +| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | + + + +## Priority adjustments + +No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: + + + +| Issue | Label | Recommendations raised (original ranking) | Reason | +| --- | --- | --- | --- | +| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | +| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | +| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | +| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | +| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | +| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | +| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | +| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | +| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | +| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | +| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | +| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | +| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | +| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | +| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | +| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | +| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | +| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | +| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | From 572ef1d234a1e69be9c7a8dca1a370714d3181b7 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 19:33:34 -0700 Subject: [PATCH 25/31] tables testing Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 84ce69dc..3bbce0a5 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -9,10 +9,10 @@ uploaded as an issue. -| Issue | Title | Label | File | -| ----- | ------------------------------------------------ | ----- | ---------------------------------- | -| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | -| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | +| Issue | Title | Label | File | +| --- | --- | --- | --- | +| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | +| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | | #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | | #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | | #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | @@ -22,7 +22,7 @@ uploaded as an issue. | #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | | #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | | #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | -| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtualmachinebackup-api.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtual-machine-backup-api.md` | | #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | | #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | | #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | @@ -84,12 +84,8 @@ uploaded as an issue. | #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | | #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | - - ## Umbrella issues - - | Umbrella | Label | Sub-issues | | --- | --- | --- | | #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | @@ -105,17 +101,13 @@ uploaded as an issue. | #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | | #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | - - Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. ## Recommendation mapping - - | # | Section | Area | CSV priority | Issue(s) | -| --- | --- | --- | --- | +| --- | --- | --- | --- | --- | | 1 | Project Documentation | Information architecture | 2 - High | #9001 | | 2 | Project Documentation | Information architecture | 2 - High | #9002 | | 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | @@ -231,13 +223,11 @@ label among its sub-issues. | 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | | 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | - ## Priority adjustments No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: - | Issue | Label | Recommendations raised (original ranking) | Reason | | --- | --- | --- | --- | From 36abf2f86ce591a08ffd8d8a0e3c106dac0af798 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 19:42:29 -0700 Subject: [PATCH 26/31] simple fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 3bbce0a5..7d4023a8 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -223,12 +223,10 @@ label among its sub-issues. | 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | | 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | - ## Priority adjustments No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: - | Issue | Label | Recommendations raised (original ranking) | Reason | | --- | --- | --- | --- | | #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | From 7971085bf004bae5c62bdbc10b734de549578f6e Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 19:48:51 -0700 Subject: [PATCH 27/31] hmmm Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues-coverage.md | 454 +++++++++++----------- 1 file changed, 228 insertions(+), 226 deletions(-) diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md index 7d4023a8..bbc6e09b 100644 --- a/analyses/2026/kubevirt/issues-coverage.md +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -9,246 +9,248 @@ uploaded as an issue. -| Issue | Title | Label | File | -| --- | --- | --- | --- | -| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | -| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | -| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | -| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | -| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | -| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | -| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | -| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | -| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | -| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | -| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | -| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtual-machine-backup-api.md` | -| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | -| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | -| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | -| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | -| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | -| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | -| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | -| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | -| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | -| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | -| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | -| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | -| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | -| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | -| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | -| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | -| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | -| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | -| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | -| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | -| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | -| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | -| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | -| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | -| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | -| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | -| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | -| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | -| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | -| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | -| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | -| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | -| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | -| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | -| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | -| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | -| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | -| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | -| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | -| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | -| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | -| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | -| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | -| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | -| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | -| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | -| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | -| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | -| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | -| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | -| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | -| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | -| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | -| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | -| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | -| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | -| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | -| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | -| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | -| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | +| Issue | Title | Label | File | +| ----- | ---------------------------------------------------------------------------------------- | ------- | ---------------------------------------------- | +| #9001 | Add a Getting Started page after Architecture | high | `9001-add-getting-started-page.md` | +| #9002 | Rewrite Basic Use as "Your first VirtualMachine" | high | `9002-rewrite-basic-use.md` | +| #9003 | Add a Start here link and fix the Slack link on the Welcome page | urgent | `9003-fix-welcome-page-links.md` | +| #9004 | Restructure the Installation page around the core procedure | urgent | `9004-restructure-installation-page.md` | +| #9005 | Create an Installing virtctl page | high | `9005-create-installing-virtctl-page.md` | +| #9006 | Enable code copy and search features in mkdocs.yml | urgent | `9006-enable-code-copy-search.md` | +| #9007 | Convert shell code blocks to fenced blocks | backlog | `9007-convert-shell-code-blocks.md` | +| #9008 | Fix orphaned pages and Release Notes placement in navigation | urgent | `9008-fix-navigation-orphans.md` | +| #9009 | Add landing pages to Compute, Network, and Storage | backlog | `9009-add-section-landing-pages.md` | +| #9010 | Rename API-centric titles and group legacy workload pages | backlog | `9010-rename-api-page-titles.md` | +| #9011 | Remove or archive legacy installation content | high | `9011-remove-legacy-installation-content.md` | +| #9012 | Document the VirtualMachineBackup API | high | `9012-document-virtual-machine-backup-api.md` | +| #9013 | Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression | high | `9013-document-v19-features.md` | +| #9014 | Create a virtctl command reference | high | `9014-create-virtctl-reference.md` | +| #9015 | Add a feature-gate table | high | `9015-add-feature-gate-table.md` | +| #9016 | Add a user-facing Troubleshooting page | high | `9016-add-troubleshooting-page.md` | +| #9017 | Standardize the feature-state admonition | high | `9017-standardize-feature-state-admonition.md` | +| #9018 | Document the content versioning model, release-notes process, and localization | high | `9018-document-versioning-model.md` | +| #9019 | Publish versioned documentation with a version selector | high | `9019-publish-versioned-docs.md` | +| #9020 | Expand CONTRIBUTING.md into a documentation contributor guide | high | `9020-expand-contributing-guide.md` | +| #9021 | Add a documentation style guide | urgent | `9021-add-style-guide.md` | +| #9022 | Add a pull request template | urgent | `9022-add-pull-request-template.md` | +| #9023 | Add per-directory OWNERS files | high | `9023-add-owners-files.md` | +| #9024 | Give documentation a SIG home and clarify SIG meeting mechanics | high | `9024-give-docs-sig-home.md` | +| #9025 | Triage open pull requests and add a stale-PR policy | high | `9025-triage-open-prs.md` | +| #9026 | Add MAINTAINERS.md and a maintainer ladder | high | `9026-add-maintainers-file.md` | +| #9027 | Reword minimizing language and cancel terminology | high | `9027-reword-minimizing-language.md` | +| #9028 | Add accessibility and language checks to CI | backlog | `9028-add-ci-doc-checks.md` | +| #9029 | Fix legacy master links and the node-name example | urgent | `9029-fix-legacy-master-references.md` | +| #9030 | Add a Community and communication page to the guide | high | `9030-add-community-page.md` | +| #9031 | Add a Community and adoption block to the index and Contributing page | urgent | `9031-add-community-adoption-links.md` | +| #9032 | Add repository and social links to the footer | urgent | `9032-add-footer-social-links.md` | +| #9033 | Fix logo alt text and remove unused assets and config | urgent | `9033-fix-logo-and-unused-assets.md` | +| #9034 | Add a project overview and resource descriptions to the Contributing page | urgent | `9034-add-contributing-overview.md` | +| #9035 | Add where-to-ask-help and the VEP docs deadline to the Contributing page | urgent | `9035-add-help-and-vep-guidance.md` | +| #9036 | Link filtered issue lists and explain labels on the Contributing page | urgent | `9036-link-issue-lists.md` | +| #9037 | Add a first documentation change walkthrough to the Contributing page | high | `9037-add-first-change-walkthrough.md` | +| #9038 | Standardize the good first issue label | urgent | `9038-standardize-good-first-issue.md` | +| #9039 | Triage the issue backlog and publish a triage cadence | high | `9039-triage-issue-backlog.md` | +| #9040 | Add a Governance section to the kubevirt.io Community page | high | `9040-add-governance-section.md` | +| #9041 | Document where documentation lives | high | `9041-document-content-boundary.md` | +| #9042 | Add an API reference entry to the guide navigation | urgent | `9042-add-api-reference-link.md` | +| #9043 | Audit kubevirt/kubevirt docs for user-facing content | backlog | `9043-audit-kubevirt-docs.md` | +| #9044 | Audit CDI documentation for storage pages | backlog | `9044-audit-cdi-docs.md` | +| #9045 | Decide whether to converge the website and user guide | high | `9045-decide-converge-toolchains.md` | +| #9046 | Bring the user guide footer into compliance | high | `9046-fix-guide-footer.md` | +| #9047 | Fix the website footer and add community health files | urgent | `9047-fix-website-footer.md` | +| #9048 | Fix header and link contrast and align brand colors | high | `9048-fix-contrast-and-colors.md` | +| #9049 | Fix mobile tables and replace the Architecture diagram | urgent | `9049-fix-mobile-tables.md` | +| #9050 | Split the Disks and Volumes and Interfaces and Networks pages | backlog | `9050-split-disks-networks-pages.md` | +| #9051 | Split the Live Migration and Release Notes pages | backlog | `9051-split-migration-release-notes.md` | +| #9052 | Publish a brand reference | backlog | `9052-publish-brand-reference.md` | +| #9053 | Add an adopters page and link CNCF case studies | urgent | `9053-add-adopters-page.md` | +| #9054 | Show adopter use cases and KubeVirt-specific vendor links | high | `9054-show-adopter-use-cases.md` | +| #9055 | Add blog categories and tags | backlog | `9055-add-blog-categories.md` | +| #9056 | Enable production-only analytics and a 404 report on the user guide | high | `9056-enable-guide-analytics.md` | +| #9057 | Fix robots.txt and gate analytics on kubevirt.io | urgent | `9057-fix-robots-and-site-analytics.md` | +| #9058 | Make guide preview builds reproducible and non-indexable | urgent | `9058-fix-guide-preview-builds.md` | +| #9059 | Unify search across the guide and the website | high | `9059-unify-search.md` | +| #9060 | Document site infrastructure ownership | high | `9060-document-site-infrastructure.md` | +| #9061 | Create a new-user getting started path | urgent | `U-9061-create-getting-started-path.md` | +| #9062 | Fix navigation gaps and reorganize information architecture | urgent | `U-9062-fix-navigation-gaps.md` | +| #9063 | Fill feature and reference coverage gaps | high | `U-9063-fill-feature-coverage-gaps.md` | +| #9064 | Publish versioned docs and standardize feature states | high | `U-9064-publish-versioned-docs.md` | +| #9065 | Build a documentation contributor guide | urgent | `U-9065-build-contributor-guide.md` | +| #9066 | Improve the Contributing page for new contributors | urgent | `U-9066-improve-contributing-page.md` | +| #9067 | Document community channels and governance | urgent | `U-9067-document-community-channels.md` | +| #9068 | Apply inclusive language and legacy naming updates | urgent | `U-9068-inclusive-language-updates.md` | +| #9069 | Apply accessibility and branding improvements | urgent | `U-9069-accessibility-improvements.md` | +| #9070 | Fix website compliance and adopter content | urgent | `U-9070-fix-website-compliance.md` | +| #9071 | Enable analytics and fix SEO configuration | urgent | `U-9071-enable-analytics-seo.md` | +| #9072 | Document site ownership and content boundaries | high | `U-9072-document-site-ownership.md` | ## Umbrella issues -| Umbrella | Label | Sub-issues | -| --- | --- | --- | -| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | +| Umbrella | Label | Sub-issues | +| ----------------------------------------------------------------- | ------ | ----------------------------------------------- | +| #9061 Create a new-user getting started path | urgent | #9006, #9004, #9005, #9001, #9002, #9003, #9007 | | #9062 Fix navigation gaps and reorganize information architecture | urgent | #9008, #9042, #9011, #9009, #9010, #9050, #9051 | -| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | -| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | -| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | -| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | -| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | -| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | -| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | -| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | -| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | -| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | +| #9063 Fill feature and reference coverage gaps | high | #9012, #9013, #9014, #9015, #9016 | +| #9064 Publish versioned docs and standardize feature states | high | #9017, #9018, #9019 | +| #9065 Build a documentation contributor guide | urgent | #9022, #9021, #9020, #9023, #9026, #9025 | +| #9066 Improve the Contributing page for new contributors | urgent | #9038, #9034, #9036, #9035, #9037, #9039 | +| #9067 Document community channels and governance | urgent | #9032, #9030, #9031, #9040, #9024 | +| #9068 Apply inclusive language and legacy naming updates | urgent | #9029, #9027, #9028 | +| #9069 Apply accessibility and branding improvements | urgent | #9033, #9049, #9048, #9052 | +| #9070 Fix website compliance and adopter content | urgent | #9047, #9046, #9053, #9054, #9055 | +| #9071 Enable analytics and fix SEO configuration | urgent | #9058, #9057, #9056, #9059 | +| #9072 Document site ownership and content boundaries | high | #9041, #9060, #9045, #9043, #9044 | Standalone issues outside any umbrella: none. Each umbrella takes the highest label among its sub-issues. ## Recommendation mapping -| # | Section | Area | CSV priority | Issue(s) | -| --- | --- | --- | --- | --- | -| 1 | Project Documentation | Information architecture | 2 - High | #9001 | -| 2 | Project Documentation | Information architecture | 2 - High | #9002 | -| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | -| 5 | Project Documentation | Information architecture | 2 - High | #9014 | -| 6 | Project Documentation | Information architecture | 2 - High | #9015 | -| 7 | Project Documentation | Information architecture | 2 - High | #9016 | -| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | -| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | -| 11 | Project Documentation | Information architecture | 2 - High | #9011 | -| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | -| 14 | Project Documentation | New user content | 2 - High | #9001 | -| 15 | Project Documentation | New user content | 2 - High | #9004 | -| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | -| 17 | Project Documentation | New user content | 2 - High | #9004 | -| 18 | Project Documentation | New user content | 2 - High | #9005 | -| 19 | Project Documentation | New user content | 2 - High | #9002 | -| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | -| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | -| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | -| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | -| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | -| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | -| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | -| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | -| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | -| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | -| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | -| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | -| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | -| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | -| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | -| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | -| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | -| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | -| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | -| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | -| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | -| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | -| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | -| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | -| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | -| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | -| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | -| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | -| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | -| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | -| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | -| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | -| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | -| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | -| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | -| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | -| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | -| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | -| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | -| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | -| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | -| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | -| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | -| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | -| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | -| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | -| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | -| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | -| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | -| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | -| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | -| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | -| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | -| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | -| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | -| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | -| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | -| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | -| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | -| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | -| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | -| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | -| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | -| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | -| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | -| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | -| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | -| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | -| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | -| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | -| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | -| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | -| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | -| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | -| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | -| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | -| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | -| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | -| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | -| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | -| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | -| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | -| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | -| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| # | Section | Area | CSV priority | Issue(s) | +| --- | ------------------------- | ---------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | +| 1 | Project Documentation | Information architecture | 2 - High | #9001 | +| 2 | Project Documentation | Information architecture | 2 - High | #9002 | +| 3 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 4 | Project Documentation | Information architecture | 2 - High | #9012, #9013 | +| 5 | Project Documentation | Information architecture | 2 - High | #9014 | +| 6 | Project Documentation | Information architecture | 2 - High | #9015 | +| 7 | Project Documentation | Information architecture | 2 - High | #9016 | +| 8 | Project Documentation | Information architecture | 3 - Backlog | #9009 | +| 9 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 10 | Project Documentation | Information architecture | 3 - Backlog | #9010 | +| 11 | Project Documentation | Information architecture | 2 - High | #9011 | +| 12 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 13 | Project Documentation | Information architecture | 1 - Urgent | #9008 | +| 14 | Project Documentation | New user content | 2 - High | #9001 | +| 15 | Project Documentation | New user content | 2 - High | #9004 | +| 16 | Project Documentation | New user content | 1 - Urgent | #9004 | +| 17 | Project Documentation | New user content | 2 - High | #9004 | +| 18 | Project Documentation | New user content | 2 - High | #9005 | +| 19 | Project Documentation | New user content | 2 - High | #9002 | +| 20 | Project Documentation | New user content | 1 - Urgent | #9006 | +| 21 | Project Documentation | New user content | 3 - Backlog | #9007 | +| 22 | Project Documentation | New user content | 3 - Backlog | #9001 | +| 23 | Project Documentation | New user content | 1 - Urgent | #9003 | +| 24 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9018 | +| 25 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9019 | +| 26 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9017 | +| 27 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 28 | Project Documentation | Content maintainability & site mechanics | 1 - Urgent | #9006 | +| 29 | Project Documentation | Content maintainability & site mechanics | 3 - Backlog | #9018 | +| 30 | Project Documentation | Content maintainability & site mechanics | 2 - High | #9059 | +| 31 | Project Documentation | Content creation processes | 2 - High | #9020 | +| 32 | Project Documentation | Content creation processes | 2 - High | #9026 | +| 33 | Project Documentation | Content creation processes | 2 - High | #9021 | +| 34 | Project Documentation | Content creation processes | 1 - Urgent | #9022 | +| 35 | Project Documentation | Content creation processes | 2 - High | #9023 | +| 36 | Project Documentation | Content creation processes | 2 - High | #9024 | +| 37 | Project Documentation | Content creation processes | 1 - Urgent | #9035 | +| 38 | Project Documentation | Content creation processes | 2 - High | #9025 | +| 39 | Project Documentation | Inclusive language | 3 - Backlog | #9027 | +| 40 | Project Documentation | Inclusive language | 1 - Urgent | #9021 | +| 41 | Project Documentation | Inclusive language | 3 - Backlog | #9028 | +| 42 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 43 | Project Documentation | Inclusive language | 1 - Urgent | #9029 | +| 44 | Project Documentation | Inclusive language | 2 - High | #9027 | +| 45 | Project Documentation | Inclusive language | 3 - Backlog | #9029 | +| 46 | Contributor documentation | Communication methods documented | 2 - High | #9030 | +| 47 | Contributor documentation | Communication methods documented | 3 - Backlog | #9030 | +| 48 | Contributor documentation | Communication methods documented | 1 - Urgent | #9032 | +| 49 | Contributor documentation | Communication methods documented | 1 - Urgent | #9003 | +| 50 | Contributor documentation | Beginner friendly issue backlog | 1 - Urgent | #9038 | +| 51 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 52 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 53 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9036 | +| 54 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9038 | +| 55 | Contributor documentation | Beginner friendly issue backlog | 3 - Backlog | #9039 | +| 56 | Contributor documentation | Beginner friendly issue backlog | 2 - High | #9039 | +| 57 | Contributor documentation | New contributor getting started content | 2 - High | #9037 | +| 58 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 59 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9034 | +| 60 | Contributor documentation | New contributor getting started content | 1 - Urgent | #9036 | +| 61 | Contributor documentation | New contributor getting started content | 3 - Backlog | #9037 | +| 62 | Contributor documentation | New contributor getting started content | 2 - High | #9035 | +| 63 | Contributor documentation | Project governance documentation | 2 - High | #9040 | +| 64 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 65 | Contributor documentation | Project governance documentation | 1 - Urgent | #9034 | +| 66 | Contributor documentation | Project governance documentation | 2 - High | #9024 | +| 67 | Website & Infrastructure | Single-source requirement | 2 - High | #9041 | +| 68 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9043 | +| 69 | Website & Infrastructure | Single-source requirement | 3 - Backlog | #9044 | +| 70 | Website & Infrastructure | Single-source requirement | 2 - High | #9045 | +| 71 | Website & Infrastructure | Single-source requirement | 1 - Urgent | #9042 | +| 72 | Website & Infrastructure | Website requirements | 2 - High | #9046 | +| 73 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 74 | Website & Infrastructure | Website requirements | 3 - Backlog | #9054 | +| 75 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 76 | Website & Infrastructure | Website requirements | 1 - Urgent | #9047 | +| 77 | Website & Infrastructure | Website requirements | 3 - Backlog | #9047 | +| 78 | Website & Infrastructure | Usability, accessibility and devices | 2 - High | #9048 | +| 79 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9049 | +| 80 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9007 | +| 81 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9049 | +| 82 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9050, #9051 | +| 83 | Website & Infrastructure | Usability, accessibility and devices | 1 - Urgent | #9033, #9049 | +| 84 | Website & Infrastructure | Usability, accessibility and devices | 3 - Backlog | #9028 | +| 85 | Website & Infrastructure | Branding and design | 3 - Backlog | #9052 | +| 86 | Website & Infrastructure | Branding and design | 2 - High | #9048 | +| 87 | Website & Infrastructure | Branding and design | 1 - Urgent | #9032 | +| 88 | Website & Infrastructure | Branding and design | 3 - Backlog | Not an issue — optional logo-variant preference with minimal reader impact. | +| 89 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 90 | Website & Infrastructure | Branding and design | 1 - Urgent | #9033 | +| 91 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9053 | +| 92 | Website & Infrastructure | Case studies/social proof | 2 - High | #9054 | +| 93 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9053 | +| 94 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — inviting adopters to write posts or talks is community outreach, not a documentation change. | +| 95 | Website & Infrastructure | Case studies/social proof | 3 - Backlog | #9055 | +| 96 | Website & Infrastructure | Case studies/social proof | 2 - High | Not an issue — a blog publishing-cadence commitment is a process decision, not a documentation change. | +| 97 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 98 | Website & Infrastructure | Case studies/social proof | 1 - Urgent | #9031 | +| 99 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056 | +| 100 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9056, #9057 | +| 101 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057, #9058 | +| 102 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9057 | +| 103 | Website & Infrastructure | SEO, Analytics and site-local search | 1 - Urgent | #9058 | +| 104 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9059 | +| 105 | Website & Infrastructure | SEO, Analytics and site-local search | 2 - High | #9060 | +| 106 | Website & Infrastructure | SEO, Analytics and site-local search | 3 - Backlog | #9056 | +| 107 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 108 | Website & Infrastructure | Maintenance planning | 2 - High | #9024 | +| 109 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | +| 110 | Website & Infrastructure | Maintenance planning | 2 - High | Not an issue — recruiting reviewers is a people action; the starter tasks it depends on are covered by #9039. | +| 111 | Website & Infrastructure | Maintenance planning | 2 - High | #9045 | +| 112 | Website & Infrastructure | Maintenance planning | 1 - Urgent | #9058 | +| 113 | Website & Infrastructure | Maintenance planning | 2 - High | #9060 | +| 114 | Website & Infrastructure | Maintenance planning | 3 - Backlog | #9026 | ## Priority adjustments -No issue takes a label lower than its highest-ranked recommendation. Each issue takes the highest ranking among its recommendations, so these recommendations were raised by bundling with higher-ranked work on the same pages or files: +No issue takes a label lower than its highest-ranked recommendation. Each issue +takes the highest ranking among its recommendations, so these recommendations +were raised by bundling with higher-ranked work on the same pages or files: -| Issue | Label | Recommendations raised (original ranking) | Reason | -| --- | --- | --- | --- | -| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | -| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | -| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | -| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | -| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | -| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | -| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | -| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | -| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | -| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | -| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | -| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | -| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | -| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | -| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | -| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | -| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | -| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | -| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | -| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | +| Issue | Label | Recommendations raised (original ranking) | Reason | +| ----- | ------ | ----------------------------------------- | --------------------------------------------------------------------------- | +| #9001 | high | 22 (backlog) | The Quickstarts introduction links to the new Getting Started page. | +| #9004 | urgent | 15, 17 (high) | Same page edit as the urgent "Next steps" section. | +| #9018 | high | 27, 29 (backlog) | Short `CONTRIBUTING.md` additions that belong next to the versioning model. | +| #9021 | urgent | 33 (high) | The style guide carries the urgent minimizing-language rule. | +| #9026 | high | 109, 114 (backlog) | Maintainer documentation belongs with the `MAINTAINERS.md` work. | +| #9027 | high | 39 (backlog) | Shares prose edits with the high-ranked cancel terminology question. | +| #9029 | urgent | 45 (backlog) | Same legacy-branch link cleanup as the urgent `master` links. | +| #9030 | high | 47 (backlog) | Meeting details belong on the same community page. | +| #9035 | urgent | 58, 62 (high) | Same Contributing page section as the urgent VEP deadline. | +| #9036 | urgent | 53 (backlog) | Label explanation sits beside the urgent filtered issue links. | +| #9037 | high | 61 (backlog) | Same walkthrough section of the Contributing page. | +| #9038 | urgent | 54 (backlog) | Same label and lifecycle policy as the urgent label consolidation. | +| #9039 | high | 55 (backlog) | The issue checklist supports the triage cadence. | +| #9047 | urgent | 77 (backlog) | Same footer file edits as the urgent copyright fix. | +| #9049 | urgent | 79 (backlog) | Both fix content that fails on mobile or for screen readers. | +| #9053 | urgent | 93 (backlog) | The adopters page is where the urgent case study links live. | +| #9054 | high | 74 (backlog) | Same `ADOPTERS.md` data work. | +| #9056 | high | 106 (backlog) | Depends on the analytics setup in the same issue. | +| #9057 | urgent | 100 (high) | Same `robots.txt` and head template changes on the website. | +| #9059 | high | 104 (backlog) | Same search index work as the high-ranked question. | From c74072e413c1a70426ff360697747add50154733 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 19:54:26 -0700 Subject: [PATCH 28/31] Trigger build after timeout Signed-off-by: Bruce Hamilton From 72db16247b81a1484c5f6235caf641525b7601e4 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 22:01:13 -0700 Subject: [PATCH 29/31] recopied issue files from source Signed-off-by: Bruce Hamilton --- .../issues/9009-add-section-landing-pages.md | 3 +++ .../kubevirt/issues/9010-rename-api-page-titles.md | 5 ----- .../2026/kubevirt/issues/9023-add-owners-files.md | 7 ++++--- .../kubevirt/issues/9026-add-maintainers-file.md | 4 ++-- .../issues/9034-add-contributing-overview.md | 4 ++-- .../issues/9035-add-help-and-vep-guidance.md | 2 +- .../2026/kubevirt/issues/9036-link-issue-lists.md | 2 +- .../issues/9041-document-content-boundary.md | 6 +++--- .../issues/9052-publish-brand-reference.md | 4 ++-- .../kubevirt/issues/9054-show-adopter-use-cases.md | 1 + analyses/2026/kubevirt/issues/9059-unify-search.md | 1 + .../issues/9060-document-site-infrastructure.md | 5 ++--- .../issues/U-9061-create-getting-started-path.md | 14 +++++++------- .../kubevirt/issues/U-9062-fix-navigation-gaps.md | 14 +++++++------- .../issues/U-9063-fill-feature-coverage-gaps.md | 6 +++--- .../issues/U-9064-publish-versioned-docs.md | 6 +++--- .../issues/U-9065-build-contributor-guide.md | 6 +++--- .../issues/U-9066-improve-contributing-page.md | 12 ++++++------ .../issues/U-9067-document-community-channels.md | 10 +++++----- .../issues/U-9068-inclusive-language-updates.md | 6 +++--- .../issues/U-9069-accessibility-improvements.md | 6 +++--- .../issues/U-9070-fix-website-compliance.md | 8 ++++---- .../kubevirt/issues/U-9071-enable-analytics-seo.md | 8 ++++---- .../issues/U-9072-document-site-ownership.md | 10 +++++----- 24 files changed, 75 insertions(+), 75 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md index 9a93043d..ee79d332 100644 --- a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -32,6 +32,9 @@ page for each common task. ## URL +- https://kubevirt.io/user-guide/compute/ +- https://kubevirt.io/user-guide/network/ +- https://kubevirt.io/user-guide/storage/ - New files `docs/compute/index.md`, `docs/network/index.md`, `docs/storage/index.md`; the existing `.nav.yml` files in each directory diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index 72a5de72..a5920261 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -12,8 +12,6 @@ the User Workloads "Workloads" group mixes current and legacy mechanisms. Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: - - | Current title | Proposed title | | ------------------------------------------------------------- | ------------------------------------------------ | | Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | @@ -21,8 +19,6 @@ entry: | Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | | Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | - - Choose the last title after reading the page; ask the maintainers if the purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update inbound links. @@ -53,6 +49,5 @@ rename adds clear value. 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). diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 4a582afd..0e979550 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -33,9 +33,10 @@ experts, while root approvers still approve site-wide changes. - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root -- New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, and - `docs/compute/OWNERS`. -- Guide sections in compute, network, and storage. +- New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` +- Guide sections: https://kubevirt.io/user-guide/network/, + https://kubevirt.io/user-guide/storage/, + https://kubevirt.io/user-guide/compute/ ## Additional context diff --git a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md index 72b17d60..940bd7b8 100644 --- a/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -34,9 +34,9 @@ the role, and can trust that the approver list reflects active people. - Repository: https://github.com/kubevirt/user-guide (`OWNERS`, `OWNERS_ALIASES`, README) - Contributing page: https://kubevirt.io/user-guide/contributing/ - - (`docs/contributing.md`) + (`docs/contributing.md`) - kubevirt/community membership policy: - - (`https://github.com/kubevirt/community/blob/main/membership_policy.md`) + https://github.com/kubevirt/community/blob/main/membership_policy.md ## Additional context diff --git a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md index b2a4621f..88a386a7 100644 --- a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -37,8 +37,8 @@ link states what it leads to. Related: #9035, #9036, and #9037 (other additions to the same page; coordinate to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 (governance text on the Community page, which should use the same wording), and -issue #9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers -list should the page link, the community one or a user guide one? +#9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list +should the page link, the community one or a user guide one? This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md index 01375328..ed4801fd 100644 --- a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -38,7 +38,7 @@ first-time contributors exist, or could one be offered? If not, remove the mentoring note. Who is the docs contact? Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), -and #9034, #9036, #9037 (same page), and #9020. +#9034, #9036, #9037 (same page), and #9020. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md index f953af97..d4cb58dc 100644 --- a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -37,7 +37,7 @@ beginner-friendly issues, and knows what each label means. Depends on #9038 (the label name must be standardized before linking the filter) and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, -and #9037. +#9037. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md index 8fe1bbe2..8ee1150a 100644 --- a/analyses/2026/kubevirt/issues/9041-document-content-boundary.md +++ b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md @@ -36,9 +36,9 @@ guidance. ## URL - https://kubevirt.io/user-guide/contributing/ (`docs/contributing.md`) -- `https://github.com/kubevirt/user-guide/blob/main/README.md` -- `https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md` -- `https://github.com/kubevirt/kubevirt/blob/main/README.md` +- https://github.com/kubevirt/user-guide/blob/main/README.md +- https://github.com/kubevirt/kubevirt.github.io/blob/main/README.md +- https://github.com/kubevirt/kubevirt/blob/main/README.md ## Additional context diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md index f097624e..79ad54e8 100644 --- a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -38,8 +38,8 @@ stylesheet points to it. ## Additional context Related: #9048 aligns the guide's primary color with the website scale, and -issue #9033 fixes the logo alt text. Complete #9048 first so the reference lists -the final values. +#9033 fixes the logo alt text. Complete #9048 first so the reference lists the +final values. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md index 49e068a9..b4588d4e 100644 --- a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -35,6 +35,7 @@ mention KubeVirt. - https://kubevirt.io/ (End Users and Vendors logo walls) - https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/adopters.yml +- https://github.com/kubevirt/kubevirt.github.io/blob/main/ADOPTERS.md ## Additional context diff --git a/analyses/2026/kubevirt/issues/9059-unify-search.md b/analyses/2026/kubevirt/issues/9059-unify-search.md index 83724482..a70d9ca2 100644 --- a/analyses/2026/kubevirt/issues/9059-unify-search.md +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -32,6 +32,7 @@ and the maintainers' decision about a single search index is recorded. ## URL - https://kubevirt.io/user-guide/ (search box) +- https://kubevirt.io/search/ - https://github.com/kubevirt/kubevirt.github.io/blob/main/_layouts/search.html ## Additional context diff --git a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md index ee6cff33..e0fa4111 100644 --- a/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -42,11 +42,10 @@ infrastructure, how to request access, and the known HSTS gap. ## Additional context Related: #9041 adds a "Where documentation lives" section to the same READMEs, -issues #9056 and #9057 enable and gate analytics, and #9045 records the -toolchain decision. +and #9056 and #9057 enable and gate analytics, and #9045 records the toolchain +decision. 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). diff --git a/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md index eacca446..f035f1d7 100644 --- a/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md +++ b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md @@ -20,10 +20,10 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Enable code copy features #9006](9006-enable-code-copy-search.md) -- [Restructure Install page #9004](9004-restructure-installation-page.md) -- [Create Install virtctl page #9005](9005-create-installing-virtctl-page.md) -- [Add a Getting Started page #9001](9001-add-getting-started-page.md) -- [Rewrite Basic Use #9002](9002-rewrite-basic-use.md) -- [Add a Start here link #9003](9003-fix-welcome-page-links.md) -- [Convert shell code blocks #9007](9007-convert-shell-code-blocks.md) +- [Enable code copy and search features in mkdocs.yml #9006](9006-enable-code-copy-search.md) +- [Restructure the Installation page around the core procedure #9004](9004-restructure-installation-page.md) +- [Create an Installing virtctl page #9005](9005-create-installing-virtctl-page.md) +- [Add a Getting Started page after Architecture #9001](9001-add-getting-started-page.md) +- [Rewrite Basic Use as "Your first VirtualMachine" #9002](9002-rewrite-basic-use.md) +- [Add a Start here link and fix the Slack link on the Welcome page #9003](9003-fix-welcome-page-links.md) +- [Convert shell code blocks to fenced blocks #9007](9007-convert-shell-code-blocks.md) diff --git a/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md index 3a13a773..45b1dabe 100644 --- a/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md +++ b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md @@ -20,10 +20,10 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Fix orphaned pages and Release Notes #9008](9008-fix-navigation-orphans.md) -- [Add an API reference entry #9042](9042-add-api-reference-link.md) -- [Remove legacy install #9011](9011-remove-legacy-installation-content.md) -- [Add landing pages #9009](9009-add-section-landing-pages.md) -- [Rename API-centric titles #9010](9010-rename-api-page-titles.md) -- [Split the Disks and Volume #9050](9050-split-disks-networks-pages.md) -- [Split the Live Migration #9051](9051-split-migration-release-notes.md) +- [Fix orphaned pages and Release Notes placement in navigation #9008](9008-fix-navigation-orphans.md) +- [Add an API reference entry to the guide navigation #9042](9042-add-api-reference-link.md) +- [Remove or archive legacy installation content #9011](9011-remove-legacy-installation-content.md) +- [Add landing pages to Compute, Network, and Storage #9009](9009-add-section-landing-pages.md) +- [Rename API-centric titles and group legacy workload pages #9010](9010-rename-api-page-titles.md) +- [Split the Disks and Volumes and Interfaces and Networks pages #9050](9050-split-disks-networks-pages.md) +- [Split the Live Migration and Release Notes pages #9051](9051-split-migration-release-notes.md) diff --git a/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md index 3855d0f0..d947c098 100644 --- a/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md +++ b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md @@ -20,8 +20,8 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Doc VirtualMachineBackup #9012](9012-document-virtualmachinebackup-api.md) -- [Doc CrossArchitectureVirtualization #9013](9013-document-v19-features.md) +- [Document the VirtualMachineBackup API #9012](9012-document-virtualmachinebackup-api.md) +- [Document the CrossArchitectureVirtualization gate, PortRanges, and migration compression #9013](9013-document-v19-features.md) - [Create a virtctl command reference #9014](9014-create-virtctl-reference.md) - [Add a feature-gate table #9015](9015-add-feature-gate-table.md) -- [Add user-facing Troubleshooting #9016](9016-add-troubleshooting-page.md) +- [Add a user-facing Troubleshooting page #9016](9016-add-troubleshooting-page.md) diff --git a/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md index d267ea81..d422073f 100644 --- a/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md +++ b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md @@ -20,6 +20,6 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Standardize feature #9017](9017-standardize-feature-state-admonition.md) -- [Document the content versioning #9018](9018-document-versioning-model.md) -- [Publish versioned documentation #9019](9019-publish-versioned-docs.md) +- [Standardize the feature-state admonition #9017](9017-standardize-feature-state-admonition.md) +- [Document the content versioning model, release-notes process, and localization #9018](9018-document-versioning-model.md) +- [Publish versioned documentation with a version selector #9019](9019-publish-versioned-docs.md) diff --git a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md index 7e951097..1c48b446 100644 --- a/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md +++ b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md @@ -21,7 +21,7 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). - [Add a pull request template #9022](9022-add-pull-request-template.md) - [Add a documentation style guide #9021](9021-add-style-guide.md) -- [Expand CONTRIBUTING.md #9020](9020-expand-contributing-guide.md) +- [Expand CONTRIBUTING.md into a documentation contributor guide #9020](9020-expand-contributing-guide.md) - [Add per-directory OWNERS files #9023](9023-add-owners-files.md) -- [Add MAINTAINERS.md #9026](9026-add-maintainers-file.md) -- [Triage open pull requests #9025](9025-triage-open-prs.md) +- [Add MAINTAINERS.md and a maintainer ladder #9026](9026-add-maintainers-file.md) +- [Triage open pull requests and add a stale-PR policy #9025](9025-triage-open-prs.md) diff --git a/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md index f080b089..0bd1508f 100644 --- a/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md +++ b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md @@ -19,9 +19,9 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Standardize the good first issue #9038](9038-standardize-good-first-issue.md) -- [Add a project overview #9034](9034-add-contributing-overview.md) -- [Link filtered issue lists #9036](9036-link-issue-lists.md) -- [Add where-to-ask-help #9035](9035-add-help-and-vep-guidance.md) -- [Add a first documentation #9037](9037-add-first-change-walkthrough.md) -- [Triage the issue backlog #9039](9039-triage-issue-backlog.md) +- [Standardize the good first issue label #9038](9038-standardize-good-first-issue.md) +- [Add a project overview and resource descriptions to the Contributing page #9034](9034-add-contributing-overview.md) +- [Link filtered issue lists and explain labels on the Contributing page #9036](9036-link-issue-lists.md) +- [Add where-to-ask-help and the VEP docs deadline to the Contributing page #9035](9035-add-help-and-vep-guidance.md) +- [Add a first documentation change walkthrough to the Contributing page #9037](9037-add-first-change-walkthrough.md) +- [Triage the issue backlog and publish a triage cadence #9039](9039-triage-issue-backlog.md) diff --git a/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md index 3af28e0d..a27c33bb 100644 --- a/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md +++ b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md @@ -20,8 +20,8 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Add repository and social links #9032](9032-add-footer-social-links.md) -- [Add a Community and communication page #9030](9030-add-community-page.md) -- [Add a Community and adoption block #9031](9031-add-community-adoption-links.md) -- [Add a Governance section #9040](9040-add-governance-section.md) -- [Give documentation a SIG home #9024](9024-give-docs-sig-home.md) +- [Add repository and social links to the footer #9032](9032-add-footer-social-links.md) +- [Add a Community and communication page to the guide #9030](9030-add-community-page.md) +- [Add a Community and adoption block to the index and Contributing page #9031](9031-add-community-adoption-links.md) +- [Add a Governance section to the kubevirt.io Community page #9040](9040-add-governance-section.md) +- [Give documentation a SIG home and clarify SIG meeting mechanics #9024](9024-give-docs-sig-home.md) diff --git a/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md index de59839c..ee1ffad0 100644 --- a/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md +++ b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md @@ -19,6 +19,6 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Fix legacy master links #9029](9029-fix-legacy-master-references.md) -- [Reword minimizing language #9027](9027-reword-minimizing-language.md) -- [Add accessibility #9028](9028-add-ci-doc-checks.md) +- [Fix legacy master links and the node-name example #9029](9029-fix-legacy-master-references.md) +- [Reword minimizing language and cancel terminology #9027](9027-reword-minimizing-language.md) +- [Add accessibility and language checks to CI #9028](9028-add-ci-doc-checks.md) diff --git a/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md index a9d826c6..ad4f4b2c 100644 --- a/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md +++ b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md @@ -20,7 +20,7 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Fix logo alt text #9033](9033-fix-logo-and-unused-assets.md) -- [Fix mobile tables #9049](9049-fix-mobile-tables.md) -- [Fix header and link contrast #9048](9048-fix-contrast-and-colors.md) +- [Fix logo alt text and remove unused assets and config #9033](9033-fix-logo-and-unused-assets.md) +- [Fix mobile tables and replace the Architecture diagram #9049](9049-fix-mobile-tables.md) +- [Fix header and link contrast and align brand colors #9048](9048-fix-contrast-and-colors.md) - [Publish a brand reference #9052](9052-publish-brand-reference.md) diff --git a/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md index 3eafd4f6..72824fef 100644 --- a/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md +++ b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md @@ -19,8 +19,8 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Fix the website footer #9047](9047-fix-website-footer.md) -- [Bring user guide footer into compliance #9046](9046-fix-guide-footer.md) -- [Add an adopters page 9053](9053-add-adopters-page.md) -- [Show adopter use cases #9054](9054-show-adopter-use-cases.md) +- [Fix the website footer and add community health files #9047](9047-fix-website-footer.md) +- [Bring the user guide footer into compliance #9046](9046-fix-guide-footer.md) +- [Add an adopters page and link CNCF case studies #9053](9053-add-adopters-page.md) +- [Show adopter use cases and KubeVirt-specific vendor links #9054](9054-show-adopter-use-cases.md) - [Add blog categories and tags #9055](9055-add-blog-categories.md) diff --git a/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md index 7cd9a022..e441512e 100644 --- a/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md +++ b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md @@ -20,7 +20,7 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Make guide preview builds reproducible #9058](9058-fix-guide-preview-builds.md) -- [Fix robots.txt #9057](9057-fix-robots-and-site-analytics.md) -- [Enable production-only analytics #9056](9056-enable-guide-analytics.md) -- [Unify search across the guide #9059](9059-unify-search.md) +- [Make guide preview builds reproducible and non-indexable #9058](9058-fix-guide-preview-builds.md) +- [Fix robots.txt and gate analytics on kubevirt.io #9057](9057-fix-robots-and-site-analytics.md) +- [Enable production-only analytics and a 404 report on the user guide #9056](9056-enable-guide-analytics.md) +- [Unify search across the guide and the website #9059](9059-unify-search.md) diff --git a/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md index 2bbd3304..3c8d00ca 100644 --- a/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md +++ b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md @@ -21,8 +21,8 @@ tracked in [cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). ## Sub-issues -- [Doc where documentation lives #9041](9041-document-content-boundary.md) -- [Doc site infrastructure #9060](9060-document-site-infrastructure.md) -- [Decide whether to converge #9045](9045-decide-converge-toolchains.md) -- [Audit kubevirt/kubevirt docs #9043](9043-audit-kubevirt-docs.md) -- [Audit CDI documentation #9044](9044-audit-cdi-docs.md) +- [Document where documentation lives #9041](9041-document-content-boundary.md) +- [Document site infrastructure ownership #9060](9060-document-site-infrastructure.md) +- [Decide whether to converge the website and user guide #9045](9045-decide-converge-toolchains.md) +- [Audit kubevirt/kubevirt docs for user-facing content #9043](9043-audit-kubevirt-docs.md) +- [Audit CDI documentation for storage pages #9044](9044-audit-cdi-docs.md) From db22607e7411ad1751d51151f7a41aea5dccb5b0 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 22:19:40 -0700 Subject: [PATCH 30/31] format fixes Signed-off-by: Bruce Hamilton --- analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md | 4 ++++ .../2026/kubevirt/issues/9034-add-contributing-overview.md | 4 ++-- .../2026/kubevirt/issues/9035-add-help-and-vep-guidance.md | 2 +- analyses/2026/kubevirt/issues/9036-link-issue-lists.md | 2 +- analyses/2026/kubevirt/issues/9052-publish-brand-reference.md | 4 ++-- 5 files changed, 10 insertions(+), 6 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md index a5920261..0eaf9074 100644 --- a/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -12,6 +12,8 @@ the User Workloads "Workloads" group mixes current and legacy mechanisms. Rename these titles, changing the first H1 in each file and the `.nav.yml` entry: + + | Current title | Proposed title | | ------------------------------------------------------------- | ------------------------------------------------ | | Clone API (`docs/storage/clone_api.md`) | Cloning VirtualMachines | @@ -19,6 +21,8 @@ entry: | Snapshot Restore API (`docs/storage/snapshot_restore_api.md`) | Snapshotting and restoring VirtualMachines | | Migration Controller (`docs/storage/migration_controller.md`) | A title that states what the reader accomplishes | + + Choose the last title after reading the page; ask the maintainers if the purpose is unclear. If you rename a file, add a redirect in `mkdocs.yml` and update inbound links. diff --git a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md index 88a386a7..37a95705 100644 --- a/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -37,8 +37,8 @@ link states what it leads to. Related: #9035, #9036, and #9037 (other additions to the same page; coordinate to avoid conflicts), #9026 (`MAINTAINERS.md` for the user guide), #9040 (governance text on the Community page, which should use the same wording), and -#9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers list -should the page link, the community one or a user guide one? +issue #9020 (`CONTRIBUTING.md`). Question for the maintainers: Which maintainers +list the page link, the community one or a user guide one? This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md index ed4801fd..e8ae580f 100644 --- a/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -38,7 +38,7 @@ first-time contributors exist, or could one be offered? If not, remove the mentoring note. Who is the docs contact? Related: #9030 (Community page, for meeting times), #9026 (`MAINTAINERS.md`), -#9034, #9036, #9037 (same page), and #9020. +issue #9034, #9036, #9037 (same page), and #9020. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md index d4cb58dc..f953af97 100644 --- a/analyses/2026/kubevirt/issues/9036-link-issue-lists.md +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -37,7 +37,7 @@ beginner-friendly issues, and knows what each label means. Depends on #9038 (the label name must be standardized before linking the filter) and works best after #9039 (populated, triaged backlog). Related: #9034, #9035, -#9037. +and #9037. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). diff --git a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md index 79ad54e8..f097624e 100644 --- a/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -38,8 +38,8 @@ stylesheet points to it. ## Additional context Related: #9048 aligns the guide's primary color with the website scale, and -#9033 fixes the logo alt text. Complete #9048 first so the reference lists the -final values. +issue #9033 fixes the logo alt text. Complete #9048 first so the reference lists +the final values. This issue tracks recommended changes resulting from an analysis of the KubeVirt documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). From 4c081809ffa21ac17828f41e06dae3a28712c822 Mon Sep 17 00:00:00 2001 From: Bruce Hamilton Date: Wed, 14 Oct 2026 22:45:06 -0700 Subject: [PATCH 31/31] link fixes Signed-off-by: Bruce Hamilton --- .../2026/kubevirt/issues/9009-add-section-landing-pages.md | 6 +++--- analyses/2026/kubevirt/issues/9023-add-owners-files.md | 6 +++--- .../2026/kubevirt/issues/9054-show-adopter-use-cases.md | 2 +- analyses/2026/kubevirt/issues/9059-unify-search.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md index ee79d332..6b81cdc9 100644 --- a/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -32,9 +32,9 @@ page for each common task. ## URL -- https://kubevirt.io/user-guide/compute/ -- https://kubevirt.io/user-guide/network/ -- https://kubevirt.io/user-guide/storage/ +- `https://kubevirt.io/user-guide/compute/` +- `https://kubevirt.io/user-guide/network/` +- `https://kubevirt.io/user-guide/storage/` - New files `docs/compute/index.md`, `docs/network/index.md`, `docs/storage/index.md`; the existing `.nav.yml` files in each directory diff --git a/analyses/2026/kubevirt/issues/9023-add-owners-files.md b/analyses/2026/kubevirt/issues/9023-add-owners-files.md index 0e979550..9d90c7fd 100644 --- a/analyses/2026/kubevirt/issues/9023-add-owners-files.md +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -34,9 +34,9 @@ experts, while root approvers still approve site-wide changes. - Repository: https://github.com/kubevirt/user-guide - `OWNERS` and `OWNERS_ALIASES` in the repository root - New files: `docs/network/OWNERS`, `docs/storage/OWNERS`, `docs/compute/OWNERS` -- Guide sections: https://kubevirt.io/user-guide/network/, - https://kubevirt.io/user-guide/storage/, - https://kubevirt.io/user-guide/compute/ +- Guide sections: `https://kubevirt.io/user-guide/network/`, + `https://kubevirt.io/user-guide/storage/`, + `https://kubevirt.io/user-guide/compute/` ## Additional context diff --git a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md index b4588d4e..ea01a34f 100644 --- a/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -35,7 +35,7 @@ mention KubeVirt. - https://kubevirt.io/ (End Users and Vendors logo walls) - https://github.com/kubevirt/kubevirt.github.io/blob/main/_data/adopters.yml -- https://github.com/kubevirt/kubevirt.github.io/blob/main/ADOPTERS.md +- `https://github.com/kubevirt/kubevirt.github.io/blob/main/ADOPTERS.md` ## Additional context diff --git a/analyses/2026/kubevirt/issues/9059-unify-search.md b/analyses/2026/kubevirt/issues/9059-unify-search.md index a70d9ca2..9a88c538 100644 --- a/analyses/2026/kubevirt/issues/9059-unify-search.md +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -32,7 +32,7 @@ and the maintainers' decision about a single search index is recorded. ## URL - https://kubevirt.io/user-guide/ (search box) -- https://kubevirt.io/search/ +- `https://kubevirt.io/search/` - https://github.com/kubevirt/kubevirt.github.io/blob/main/_layouts/search.html ## Additional context