microsoft/openvmm
Publicmirrored from https://github.com/microsoft/openvmmAvailable
Guide/src/dev_guide/contrib/style_guide.md
137lines · modecode
| 1 | # Style Guide |
| 2 | |
| 3 | This page defines the writing conventions for the OpenVMM developer guide. |
| 4 | Follow these standards when creating or editing any page. |
| 5 | |
| 6 | ## Voice and tone |
| 7 | |
| 8 | Write as if explaining to a smart colleague who is new to the project. |
| 9 | Use second person ("you") for instructions: "To build OpenHCL, run..." not |
| 10 | "One can build OpenHCL by running..." State facts. Avoid hedging ("I believe", |
| 11 | "some reason", "maybe we can"). If something is uncertain, say "As of |
| 12 | [date], verify that..." |
| 13 | |
| 14 | ## Page structure |
| 15 | |
| 16 | Open every page with a one-sentence summary of what it covers. Use heading |
| 17 | levels consistently: `# Page Title`, `## Major Section`, `### Subsection`. |
| 18 | Keep pages under 400 lines. If a page grows beyond that, consider splitting |
| 19 | it into sub-pages. |
| 20 | |
| 21 | ## Callouts |
| 22 | |
| 23 | This guide uses |
| 24 | [mdbook-admonish](https://github.com/tommilligan/mdbook-admonish) for |
| 25 | callouts. Use fenced code block syntax with the `admonish` keyword: |
| 26 | |
| 27 | ~~~markdown |
| 28 | ```admonish note |
| 29 | Supplementary information the reader should be aware of. |
| 30 | ``` |
| 31 | |
| 32 | ```admonish tip |
| 33 | Helpful suggestions or shortcuts. |
| 34 | ``` |
| 35 | |
| 36 | ```admonish warning |
| 37 | Potential pitfalls or easy mistakes. |
| 38 | ``` |
| 39 | |
| 40 | ```admonish danger |
| 41 | Actions that could cause data loss or security issues. |
| 42 | ``` |
| 43 | ~~~ |
| 44 | |
| 45 | You can add a custom title with the `title` attribute: |
| 46 | |
| 47 | ~~~markdown |
| 48 | ```admonish warning title="Breaking change" |
| 49 | This API was removed in v1.8. |
| 50 | ``` |
| 51 | ~~~ |
| 52 | |
| 53 | For cross-links to related pages, use a **See also** callout: |
| 54 | |
| 55 | ~~~markdown |
| 56 | ```admonish note title="See also" |
| 57 | [Debugging OpenHCL](../../reference/openhcl/debugging.md) for serial logs, |
| 58 | crash dumps, and diagnostic tools. |
| 59 | ``` |
| 60 | ~~~ |
| 61 | |
| 62 | ## Code blocks |
| 63 | |
| 64 | ### Shell labeling |
| 65 | |
| 66 | Always specify the language. Never leave a code fence unlabeled. |
| 67 | |
| 68 | | Label | When | |
| 69 | |-------|------| |
| 70 | | `bash` | Linux / WSL / macOS shell commands | |
| 71 | | `powershell` | PowerShell commands and scripts | |
| 72 | | `rust` | Rust source code | |
| 73 | | `toml` | TOML configuration | |
| 74 | | `json` | JSON data | |
| 75 | | `text` | Plain text output, logs, or paths | |
| 76 | |
| 77 | ### Placeholders |
| 78 | |
| 79 | Two conventions are used for placeholder values. Use whichever is clearest |
| 80 | in context: |
| 81 | |
| 82 | - **`path/to/...` style** — for file paths where the structure is obvious. |
| 83 | This is the predominant style in the existing guide. |
| 84 | ```bash |
| 85 | cargo run -- --uefi --disk memdiff:file:path/to/disk.vhdx |
| 86 | ``` |
| 87 | |
| 88 | - **`<SCREAMING_SNAKE_CASE>` style** — for values that need extra emphasis or |
| 89 | where the expected format isn't obvious (build numbers, VM names, keys). |
| 90 | ```powershell |
| 91 | Set-VMComPort -VMName <VM_NAME> -Number 3 -Path \\.\pipe\<PIPE_NAME> |
| 92 | ``` |
| 93 | |
| 94 | Bad (hardcoded path that won't work for the reader): |
| 95 | |
| 96 | ~~~bash |
| 97 | cargo run -- --uefi --disk memdiff:file:/home/alice/disks/myvm.vhdx |
| 98 | ~~~ |
| 99 | |
| 100 | ### File paths in code examples |
| 101 | |
| 102 | Use **forward slashes** (Unix-style) for file paths in `bash` code blocks, |
| 103 | even when the path refers to a Windows filesystem location accessed via WSL: |
| 104 | |
| 105 | ```bash |
| 106 | # Good — forward slashes in bash |
| 107 | cargo run -- --disk memdiff:file:path/to/disk.vhdx |
| 108 | |
| 109 | # Good — wslpath output uses backslashes, but that's a Windows path |
| 110 | cargo run -- --disk "memdiff:file:$(wslpath -w /mnt/c/vhds/disk.vhdx)" |
| 111 | ``` |
| 112 | |
| 113 | Use **backslashes** for paths in `powershell` code blocks: |
| 114 | |
| 115 | ```powershell |
| 116 | # Good — backslashes in PowerShell |
| 117 | cargo run -- --disk memdiff:file:C:\vhds\disk.vhdx |
| 118 | ``` |
| 119 | |
| 120 | ### Length |
| 121 | |
| 122 | Keep code blocks under 30 lines. If longer, split with explanatory text |
| 123 | between blocks. Diagrams (ASCII art in `text` fences) are exempt from |
| 124 | this limit — keep them as a single block so the visual structure isn't |
| 125 | broken. Comments inside code blocks should explain *why*, not *what*. |
| 126 | |
| 127 | ## Line wrapping |
| 128 | |
| 129 | Wrap prose lines at approximately 80 characters. This keeps diffs |
| 130 | readable and makes review easier. Lines inside tables and code blocks |
| 131 | are exempt. |
| 132 | |
| 133 | ## Links |
| 134 | |
| 135 | Use relative links to other guide pages. When linking to external |
| 136 | documentation, prefer stable URLs (Microsoft Learn, GitHub, official docs) |
| 137 | over internal wikis or SharePoint. |
| 138 | |