guide-maintenance

Guide Maintenance Skill

Procedures for keeping the OpenVMM Guide (Guide/src/) in sync with the codebase.

.github/instructions/doc-code-sync.instructions.md contains the instructions and heuristics that are automatically loaded during Copilot code review on *.rs and Cargo.toml files.

---

Adding a New Guide Page

1. Choose the right location

Content type	Path pattern
Emulated device reference	reference/emulated/<DeviceCategory>/<device>.md
VMBus device reference	reference/devices/vmbus/<device>.md
Virtio device reference	reference/devices/virtio/<device>.md
Device backend reference	reference/backends/<category>.md
Architecture deep-dive	reference/architecture/openvmm/ or reference/architecture/openhcl/
CLI / management	reference/openvmm/management/
Developer tool	dev_guide/dev_tools/<tool>.md
Test framework	dev_guide/tests/

2. Create the page

• Follow the style in .github/instructions/guide-docs.instructions.md
• Include a brief overview, key concepts, and links to relevant rustdoc
• Reference crate names in backticks
• Use relative paths from repo root when pointing at code

3. Update SUMMARY.md

Add the page to Guide/src/SUMMARY.md in the correct section. Pages with content get a path; placeholder topics for future work get an empty link ().

- [Page Title](./reference/path/to/page.md)

---

Removing or Moving a Guide Page

1. Update or remove the entry in Guide/src/SUMMARY.md
2. Check for cross-references from other Guide pages (grep for the old path)
3. If moving: ensure the SUMMARY.md link points to the new location

---

Adding a New Device Crate

When a new crate is added under vm/devices/:

1. Does it need a Guide page? If it's a user-visible device or backend, yes. Internal plumbing crates (e.g., *_resources, *_protocol) usually don't need their own page but should be mentioned in the parent device page.

2. Create the page following the "Adding a New Guide Page" procedure above.

3. Update the "What to Flag" list if the new crate introduces a new category of reviewable change.

---

Adding or Changing CLI Arguments

When openvmm/openvmm_entry/src/cli_args.rs changes:

1. Update Guide/src/reference/openvmm/management/cli.md
2. The CLI page has a disclaimer that it may be out of date — keep it honest, but still update the page when making changes
3. New arguments should include: flag syntax, description, default value, and any interactions with other flags

---

Auditing Guide Freshness

To check whether the Guide is in sync with the code:

1. Scan the Guide pages in Guide/src/
2. Check whether the Guide page content still matches the code:
   • Crate names still correct?
   • Struct/enum names still exist?
   • Behavioral descriptions still accurate?
   • Links to rustdoc still resolve?
3. Check Guide/src/SUMMARY.md for placeholder links () — these are topics that need content. Prioritize ones whose code areas have been actively developed.

Quick audit commands

# Find Guide pages that reference a crate name
grep -r "crate_name" Guide/src/

# Find placeholder topics (empty links) in SUMMARY.md
grep '()\s*$' Guide/src/SUMMARY.md