diff --git a/.cspell.yml b/.cspell.yml index 9da23446..b5735713 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -100,3 +100,8 @@ words: - yaspeller - kubevirt - viewports + - rniw + - zstd + - vmexport + - numa + - uefi diff --git a/analyses/2026/kubevirt/issues-coverage.md b/analyses/2026/kubevirt/issues-coverage.md new file mode 100644 index 00000000..bbc6e09b --- /dev/null +++ b/analyses/2026/kubevirt/issues-coverage.md @@ -0,0 +1,264 @@ +# 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-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 | +| #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..0826bc60 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9001-add-getting-started-page.md @@ -0,0 +1,52 @@ +--- +title: Add a Getting Started page after Architecture #9001 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +A new user who has a working cluster has no single page that leads from +installation to a running VirtualMachine. The path is spread across +Installation, `virtctl`, Basic Use, and Lifecycle, so readers must assemble it +themselves. The Quickstarts page also has no introduction that explains what it +offers. + +Add a `docs/getting_started.md` page and place it immediately after Architecture +in `docs/.nav.yml`. The page walks the reader through one happy path and links +to the detailed page at each step: + +1. Install KubeVirt (link to Installation). +2. Install `virtctl` (link to the `virtctl` page). +3. Create a VirtualMachine from a provided manifest or with `virtctl create vm`. +4. Start the VirtualMachine. +5. Connect with `virtctl console`. +6. Stop the VirtualMachine. + +Add a "Try it in a sandbox" section that links to, or folds in, the Quickstarts +page. Give the Quickstarts page a one-paragraph introduction that states the +prerequisites (a laptop with virtualization enabled, or a browser for +Killercoda), the expected time, and what the reader has at the end. Close that +page with a link back to Getting Started. + +## What you expected + +A new user opens one page after Architecture and reaches a running, accessible +VirtualMachine by following numbered steps. The Quickstarts page states its +prerequisites and outcome up front. + +## URL + +- https://kubevirt.io/user-guide/ (new page after Architecture) +- https://kubevirt.io/user-guide/quickstarts/ +- `docs/.nav.yml`, `docs/quickstarts.md`, and the new `docs/getting_started.md` + +## Additional context + +Reuse the manifest from #9002 in step 3 so the two pages do not drift. If you +fold Quickstarts into the new page, add a redirect in `mkdocs.yml`. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..e31b1cd7 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9002-rewrite-basic-use.md @@ -0,0 +1,52 @@ +--- +title: Rewrite Basic Use as "Your first VirtualMachine" #9002 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Basic Use page presents `VirtualMachineInstance` commands +(`kubectl create -f vmi.yaml`) without providing the `vmi.yaml` file. It treats +the VirtualMachineInstance as the primary object, while most users manage a +VirtualMachine, which creates and owns the running instance. The Lifecycle page +repeats the undefined `vmi.yaml` reference. + +Rewrite `docs/user_workloads/basic_use.md` as a short "Your first +VirtualMachine" page: + +- Introduce VirtualMachine as the primary object and VirtualMachineInstance as + the running instance it manages. +- Include a complete minimal `vm.yaml` that uses a public containerDisk image. +- Show `kubectl apply -f vm.yaml`, `virtctl start`, `virtctl console`, and + `virtctl stop`. +- End with explicit links to the next pages, for example Creating + VirtualMachines, Accessing Virtual Machines, and Lifecycle. + +Update `docs/user_workloads/lifecycle.md` so its examples use the same `vm.yaml` +manifest instead of the undefined `vmi.yaml`. Rename the page title and the +`.nav.yml` entry in `docs/user_workloads/.nav.yml` if the file name changes, and +add a redirect in `mkdocs.yml`. + +## What you expected + +A new user copies one manifest, runs four commands, and sees a VirtualMachine +start, accept a console connection, and stop. The Lifecycle page continues from +that same manifest. + +## URL + +- https://kubevirt.io/user-guide/user_workloads/basic_use/ +- https://kubevirt.io/user-guide/user_workloads/lifecycle/ +- `docs/user_workloads/basic_use.md`, `docs/user_workloads/lifecycle.md` + +## Additional context + +The Getting Started page in #9001 reuses this manifest, so write the two pages +together or agree on the manifest first. Convert the commands to fenced blocks +as you write them (see #9007). + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..4d5a823a --- /dev/null +++ b/analyses/2026/kubevirt/issues/9003-fix-welcome-page-links.md @@ -0,0 +1,42 @@ +--- +title: Add a Start here link and fix the Slack link on the Welcome page #9003 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Welcome page lists sections but does not tell a first-time reader where to +begin. It also shows the Slack channel as a raw URL +(`https://kubernetes.slack.com/messages/virtualization`). Readers who are not +yet in the Kubernetes Slack workspace cannot open that link, and the page does +not name the channel. + +Edit `docs/index.md`: + +- Add a one-line "New to KubeVirt? Start here" link at the top that points to + the Getting Started page. +- Replace the raw Slack URL with the channel name (`#virtualization`) and a link + to the Kubernetes Slack invitation page, so readers can join the workspace + first. + +## What you expected + +A new reader sees a "Start here" link before the section list and can reach the +first-run path in one click. The Slack entry names the channel and explains how +to join the workspace. + +## URL + +- https://kubevirt.io/user-guide/ +- `docs/index.md` + +## Additional context + +Depends on #9001, which creates the Getting Started page that the new link +targets. Link to the page's final URL once it exists. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..534479ee --- /dev/null +++ b/analyses/2026/kubevirt/issues/9004-restructure-installation-page.md @@ -0,0 +1,47 @@ +--- +title: Restructure the Installation page around the core procedure #9004 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The Installation page buries the core install procedure among platform-specific +and historical material. It covers AppArmor, kernel and user-land compatibility, +SELinux, OKD, k3OS, daily developer builds, deploying from source, network +plugins, and node placement. It also keeps notes about behavior before v0.20.0 +and v0.34.2. A new user cannot tell which steps are required. + +Restructure `docs/cluster_admin/installation.md`: + +- Put the core procedure first: Requirements, the four-command operator install, + verification, and the emulation fallback. +- Move the topics listed above under a "Platform-specific and advanced + installation" heading, or split them into separate pages in + `docs/cluster_admin/` and add them to `docs/cluster_admin/.nav.yml`. +- Remove the historical notes about v0.20.0 and v0.34.2, or move them to a + footnote. Does any supported upgrade path still require them? +- End the page with a "Next steps" section that links to installing `virtctl`, + Creating VirtualMachines by using virtctl, and Accessing Virtual Machines. + +## What you expected + +The first screen of the page contains the steps needed to install KubeVirt and +verify the result. Advanced and platform-specific topics are clearly separated, +and the page ends with links to the next tasks. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/installation/ +- `docs/cluster_admin/installation.md`, `docs/cluster_admin/.nav.yml` + +## Additional context + +The "Next steps" link to installing `virtctl` targets the page created in #9005. +Coordinate with #9011, which removes legacy installation content from the same +page. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..a98add29 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9005-create-installing-virtctl-page.md @@ -0,0 +1,47 @@ +--- +title: Create an Installing virtctl page #9005 +labels: [high, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The `virtctl` page, titled "Download and Install the virtctl Command Line +Interface", does not cover all published client binaries. New users need +`virtctl` for nearly every first task, and the page sits in the middle of the +User Workloads list, far from Installation. + +Edit `docs/user_workloads/virtctl_client_tool.md`: + +- Rename the title to "Installing virtctl". +- Use the theme's content tabs for Linux, macOS, and Windows, each with amd64 + and arm64 downloads. +- Add `pymdownx.tabbed` with `alternate_style: true` to `markdown_extensions` in + `mkdocs.yml` if it is not already enabled. +- Include the `chmod +x` and `PATH` steps for each platform. +- Move the page next to Installation, for example into `docs/cluster_admin/`, or + keep it in place and link to it from the Installation page's "Next steps" + section. +- Add a redirect in `mkdocs.yml` if the file moves, and update `.nav.yml`. + +## What you expected + +A reader on any supported operating system and CPU architecture finds the right +binary, makes it executable, and puts it on their `PATH` from one page. The page +is easy to find from Installation. + +## URL + +- https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/ +- `docs/user_workloads/virtctl_client_tool.md`, `docs/user_workloads/.nav.yml` + +## Additional context + +The Installation restructure in #9004 links to this page from its "Next steps" +section. Ask the maintainers which binaries the release process publishes so the +tab list is accurate. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..da556905 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9006-enable-code-copy-search.md @@ -0,0 +1,41 @@ +--- +title: Enable code copy and search features in mkdocs.yml #9006 +labels: [urgent, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +The guide is command-heavy, but code blocks have no copy button and the search +box has no suggestions, highlighting, or sharing. The `mkdocs-material` theme +provides these as feature flags, and they are not enabled in `mkdocs.yml`. + +Add the following entries to the `theme.features` list in `mkdocs.yml`: + +- `content.code.copy` adds a copy button to every code block. +- `search.suggest` shows completion suggestions while the reader types. +- `search.highlight` highlights matched terms on the destination page. +- `search.share` adds a button that shares a link to the current search. + +Build the site locally with `mkdocs serve` and confirm that the copy button +appears on a code block and that search suggests and highlights terms. + +## What you expected + +Every code block has a copy button, and search suggests terms, highlights +matches on the result page, and offers a shareable link. + +## URL + +- https://kubevirt.io/user-guide/ (all pages) +- `mkdocs.yml` + +## Additional context + +The copy button works best once the shell prompt characters are removed from +code blocks (see #9007). This is a small change and a good first contribution. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..bd443a89 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9007-convert-shell-code-blocks.md @@ -0,0 +1,53 @@ +--- +title: Convert shell code blocks to fenced blocks #9007 +labels: [backlog, help wanted] +repo: https://github.com/kubevirt/user-guide/issues +--- + +## Description + +Many pages use indented code blocks with a `$` prompt, for example +`$ kubectl create -f vmi.yaml`. Readers cannot paste these commands without +removing the prompt, indented blocks get no syntax highlighting, and the copy +button does not skip the prompt. Long lines also force horizontal scrolling on +mobile devices and are hard for screen readers to navigate. + +Convert the blocks in this order, one pull request per group: + +1. The new-user path: Installation, `virtctl`, Basic Use, and Lifecycle. +2. The longest reference pages: Disks and Volumes and Export API. + +For each block: + +- Replace the indented block with a fenced block with the `shell` language tag + and remove the `$` prompt. +- Move example output to a separate block, or add a `title="Output"` annotation. +- Break commands longer than 100 characters over several lines with `\` + continuations so they do not need horizontal scrolling. + +## What you expected + +Commands on the converted pages paste directly into a terminal, and output is +visibly separate from commands. No command line requires horizontal scrolling on +a phone. + +## URL + +- https://kubevirt.io/user-guide/cluster_admin/installation/ +- https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/ +- https://kubevirt.io/user-guide/user_workloads/basic_use/ +- https://kubevirt.io/user-guide/user_workloads/lifecycle/ +- https://kubevirt.io/user-guide/storage/disks_and_volumes/ +- https://kubevirt.io/user-guide/storage/export_api/ +- Matching files under `docs/cluster_admin/`, `docs/user_workloads/`, and + `docs/storage/` + +## Additional context + +If #9002, #9004, or #9005 are in progress, convert those pages as part of the +rewrite to avoid merge conflicts. Enabling the copy button is tracked in #9006. + +This issue tracks recommended changes resulting from an analysis of the KubeVirt +documentation commissioned by [CNCF](https://www.cncf.io/projects/kubevirt/). +The assistance request is tracked in +[cncf/techdocs#343](https://github.com/cncf/techdocs/issues/343). 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..a04117d9 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9008-fix-navigation-orphans.md @@ -0,0 +1,52 @@ +--- +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..9a93043d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9009-add-section-landing-pages.md @@ -0,0 +1,46 @@ +--- +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 + +- 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..72a5de72 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9010-rename-api-page-titles.md @@ -0,0 +1,58 @@ +--- +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..2c4ada78 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9011-remove-legacy-installation-content.md @@ -0,0 +1,47 @@ +--- +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..0a86b1cd --- /dev/null +++ b/analyses/2026/kubevirt/issues/9012-document-virtualmachinebackup-api.md @@ -0,0 +1,49 @@ +--- +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..9fa62e8d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9013-document-v19-features.md @@ -0,0 +1,54 @@ +--- +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..997a88df --- /dev/null +++ b/analyses/2026/kubevirt/issues/9014-create-virtctl-reference.md @@ -0,0 +1,47 @@ +--- +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..3de45a4c --- /dev/null +++ b/analyses/2026/kubevirt/issues/9015-add-feature-gate-table.md @@ -0,0 +1,48 @@ +--- +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..360ffa06 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9016-add-troubleshooting-page.md @@ -0,0 +1,52 @@ +--- +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..8c3d91af --- /dev/null +++ b/analyses/2026/kubevirt/issues/9017-standardize-feature-state-admonition.md @@ -0,0 +1,54 @@ +--- +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..dc4fb828 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9018-document-versioning-model.md @@ -0,0 +1,54 @@ +--- +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..01fec5ff --- /dev/null +++ b/analyses/2026/kubevirt/issues/9019-publish-versioned-docs.md @@ -0,0 +1,53 @@ +--- +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..4fe44be0 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9020-expand-contributing-guide.md @@ -0,0 +1,50 @@ +--- +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..2cb80154 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9021-add-style-guide.md @@ -0,0 +1,54 @@ +--- +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..e50e54cb --- /dev/null +++ b/analyses/2026/kubevirt/issues/9022-add-pull-request-template.md @@ -0,0 +1,48 @@ +--- +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..4a582afd --- /dev/null +++ b/analyses/2026/kubevirt/issues/9023-add-owners-files.md @@ -0,0 +1,49 @@ +--- +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`, and + `docs/compute/OWNERS`. +- Guide sections in compute, network, and storage. + +## 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..e078c5c2 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9024-give-docs-sig-home.md @@ -0,0 +1,53 @@ +--- +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..ef50439d --- /dev/null +++ b/analyses/2026/kubevirt/issues/9025-triage-open-prs.md @@ -0,0 +1,48 @@ +--- +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..72b17d60 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9026-add-maintainers-file.md @@ -0,0 +1,52 @@ +--- +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..c65098b5 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9027-reword-minimizing-language.md @@ -0,0 +1,54 @@ +--- +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..9c5ace87 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9028-add-ci-doc-checks.md @@ -0,0 +1,50 @@ +--- +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..5a12484b --- /dev/null +++ b/analyses/2026/kubevirt/issues/9029-fix-legacy-master-references.md @@ -0,0 +1,53 @@ +--- +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..532892f7 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9030-add-community-page.md @@ -0,0 +1,51 @@ +--- +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..a103e65f --- /dev/null +++ b/analyses/2026/kubevirt/issues/9031-add-community-adoption-links.md @@ -0,0 +1,49 @@ +--- +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..e0ab8e77 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9032-add-footer-social-links.md @@ -0,0 +1,44 @@ +--- +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..b52f88c4 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9033-fix-logo-and-unused-assets.md @@ -0,0 +1,43 @@ +--- +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..b2a4621f --- /dev/null +++ b/analyses/2026/kubevirt/issues/9034-add-contributing-overview.md @@ -0,0 +1,46 @@ +--- +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 +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/). +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..01375328 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9035-add-help-and-vep-guidance.md @@ -0,0 +1,46 @@ +--- +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`), +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/). +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..f953af97 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9036-link-issue-lists.md @@ -0,0 +1,45 @@ +--- +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, +and #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..01deecf8 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9037-add-first-change-walkthrough.md @@ -0,0 +1,47 @@ +--- +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..64d6908b --- /dev/null +++ b/analyses/2026/kubevirt/issues/9038-standardize-good-first-issue.md @@ -0,0 +1,47 @@ +--- +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..40b84add --- /dev/null +++ b/analyses/2026/kubevirt/issues/9039-triage-issue-backlog.md @@ -0,0 +1,49 @@ +--- +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..f171278e --- /dev/null +++ b/analyses/2026/kubevirt/issues/9040-add-governance-section.md @@ -0,0 +1,48 @@ +--- +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..8fe1bbe2 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9041-document-content-boundary.md @@ -0,0 +1,52 @@ +--- +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..1ff28233 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9042-add-api-reference-link.md @@ -0,0 +1,45 @@ +--- +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..2f0cd5c7 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9043-audit-kubevirt-docs.md @@ -0,0 +1,50 @@ +--- +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..ab867587 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9044-audit-cdi-docs.md @@ -0,0 +1,47 @@ +--- +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..25c99e97 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9045-decide-converge-toolchains.md @@ -0,0 +1,51 @@ +--- +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..b64e0b94 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9046-fix-guide-footer.md @@ -0,0 +1,48 @@ +--- +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..b5514b99 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9047-fix-website-footer.md @@ -0,0 +1,47 @@ +--- +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..37c12c03 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9048-fix-contrast-and-colors.md @@ -0,0 +1,48 @@ +--- +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..bdacfd09 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9049-fix-mobile-tables.md @@ -0,0 +1,57 @@ +--- +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..25e24290 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9050-split-disks-networks-pages.md @@ -0,0 +1,53 @@ +--- +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..a7f5b204 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9051-split-migration-release-notes.md @@ -0,0 +1,53 @@ +--- +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..f097624e --- /dev/null +++ b/analyses/2026/kubevirt/issues/9052-publish-brand-reference.md @@ -0,0 +1,47 @@ +--- +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 +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/). +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..7cef52d3 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9053-add-adopters-page.md @@ -0,0 +1,45 @@ +--- +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..49e068a9 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9054-show-adopter-use-cases.md @@ -0,0 +1,47 @@ +--- +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 + +## 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..90402981 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9055-add-blog-categories.md @@ -0,0 +1,43 @@ +--- +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..836216fa --- /dev/null +++ b/analyses/2026/kubevirt/issues/9056-enable-guide-analytics.md @@ -0,0 +1,48 @@ +--- +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..53f25a4e --- /dev/null +++ b/analyses/2026/kubevirt/issues/9057-fix-robots-and-site-analytics.md @@ -0,0 +1,46 @@ +--- +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..a18511e7 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9058-fix-guide-preview-builds.md @@ -0,0 +1,50 @@ +--- +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..83724482 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9059-unify-search.md @@ -0,0 +1,46 @@ +--- +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://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..ee6cff33 --- /dev/null +++ b/analyses/2026/kubevirt/issues/9060-document-site-infrastructure.md @@ -0,0 +1,52 @@ +--- +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, +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/). + +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..eacca446 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9061-create-getting-started-path.md @@ -0,0 +1,29 @@ +--- +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 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 new file mode 100644 index 00000000..3a13a773 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9062-fix-navigation-gaps.md @@ -0,0 +1,29 @@ +--- +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 #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 new file mode 100644 index 00000000..3855d0f0 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9063-fill-feature-coverage-gaps.md @@ -0,0 +1,27 @@ +--- +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 + +- [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 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 new file mode 100644 index 00000000..d267ea81 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9064-publish-versioned-docs.md @@ -0,0 +1,25 @@ +--- +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 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 new file mode 100644 index 00000000..7e951097 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9065-build-contributor-guide.md @@ -0,0 +1,27 @@ +--- +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 #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) 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..f080b089 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9066-improve-contributing-page.md @@ -0,0 +1,27 @@ +--- +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 #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 new file mode 100644 index 00000000..3af28e0d --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9067-document-community-channels.md @@ -0,0 +1,27 @@ +--- +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 #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 new file mode 100644 index 00000000..de59839c --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9068-inclusive-language-updates.md @@ -0,0 +1,24 @@ +--- +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 #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 new file mode 100644 index 00000000..a9d826c6 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9069-accessibility-improvements.md @@ -0,0 +1,26 @@ +--- +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 #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 new file mode 100644 index 00000000..3eafd4f6 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9070-fix-website-compliance.md @@ -0,0 +1,26 @@ +--- +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 #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 new file mode 100644 index 00000000..7cd9a022 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9071-enable-analytics-seo.md @@ -0,0 +1,26 @@ +--- +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 #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 new file mode 100644 index 00000000..2bbd3304 --- /dev/null +++ b/analyses/2026/kubevirt/issues/U-9072-document-site-ownership.md @@ -0,0 +1,28 @@ +--- +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 + +- [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)