Glossary review by freezed · Pull Request #467 · xcp-ng/xcp-ng-org

freezed · 2026-05-11T15:50:39Z

Before submitting the pull request, you must agree with the following statements by checking both boxes with a 'x'.

"I accept that my contribution is placed under the CC BY-SA 2.0 license [1]."

"My contribution complies with the Developer Certificate of Origin [2]."

[1] https://creativecommons.org/licenses/by-sa/2.0/
[2] https://docs.xcp-ng.org/project/contributing/#developer-certificate-of-origin-dco

thomas-dkmt

Spaces before colons should be removed
DCO is missing
Checkboxes in the PR description are not checked
Emojis in commits are not that necessary. Perhaps we could remove them and flesh out the commit descriptions a little bit

freezed · 2026-05-12T12:33:40Z

rebase with --signoff

freezed · 2026-05-21T10:33:44Z

I think it's a good idea to restrict this PR on the glossary.

I'll propose other changes next.

stormi

I think you lost the original commit message when you squashed. Always double check before asking for a review 🙏.

And a few more changes:

- Use semicolons
- Order entries alphabetically
- Fix typo

stormi · 2026-05-27T10:24:27Z

-* XCP - Xen Cloud Platform
-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"


This should explain what domain 0. Not just with an external link, but with a few simple words. Like the previous version did rather well IMO.

I have no problems with previous version, it’s just that was the only term explained, all others has only acronym expansion. That’s why, in a manner of page consistance, I removed the explanation and mention an external link

I think it would be more useful to, on the contrary, have explanations inside the glossary rather than relying on external links that are not always appropriate from a pedagogical point of view. Links are a plus, but should not be mandatory to get something useful out of one's reading of a glossary.

stormi · 2026-05-27T10:25:26Z

-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"
+* DomU: Abbreviation for "[unprivileged domain](https://wiki.xenproject.org/wiki/DomU)" (no access to the hardware)


That's the Xen name for what we and most users call VMs or guests. This should be stated.

OK, that’s an important precision. I found this term when reading about dom0. I didn’t thought that it’s another name for a VM. I’ll add this precision

That been said, DomU is only mentioned in docs/project/architecture.md page, so maybe it’s relevant to update it and change the term?

domU is an important term in Xen's architecture. We use it a lot less in our docs, but I think it's still useful to mention it as a synonym to guest and virtual machine.

stormi · 2026-05-27T10:28:27Z

+* PIF: [Physical Interface](/project/architecture/#pifs)
+* PV: [Para-Virtualization](https://wiki.xenproject.org/wiki/Paravirtualization_(PV))
+* QCOW: [_QEMU Copy On Write_](https://en.wikipedia.org/wiki/Qcow), a disk image file format ([specification](https://www.qemu.org/docs/master/interop/qcow2.html))
+* RPU: [Rolling Pool Update](/management/updates/#from-xen-orchestra)


I wouldn't add it here. RPU has two meanings. Rolling Pool Update and Rolling Pool Upgrade. The later involves a different process and a change in versions. I've check the docs, we already explain what RPU is in the sections of the doc that cover it.

Fine to me. I’ll remove it.

stormi · 2026-05-27T10:30:18Z

+* PV: [Para-Virtualization](https://wiki.xenproject.org/wiki/Paravirtualization_(PV))
+* QCOW: [_QEMU Copy On Write_](https://en.wikipedia.org/wiki/Qcow), a disk image file format ([specification](https://www.qemu.org/docs/master/interop/qcow2.html))
+* RPU: [Rolling Pool Update](/management/updates/#from-xen-orchestra)
+* SMAPI: [Storage Manager API](https://github.com/xapi-project/xapi-storage)


The link is wrong. And we should make a difference between SMAPIv1 and SMAPIv3.

The link mentioned relate explicitly to SMAPIv3

Xapi storage interface ("SMAPIv3")

If you can provide a suggestion, I’ll appreciated it (-;

Exactly. This link is about SMAPIv3. It doesn't explain what SMAPI is, and SMAPI exists in several different versions (v1 and v3).

For suggestions, I let you see with your team (storage), as this is their area.

I'm the final reviewer for this doc, so I need the PR to be refined with whoever is necessary before I can do the final pass on it.

stormi · 2026-05-27T10:31:25Z

+* SMAPI: [Storage Manager API](https://github.com/xapi-project/xapi-storage)
+* SR: [Storage Repository](/storage/)
+* VBD: [Virtual Block Device](https://docs.kernel.org/block/ublk.html)
+* VDI: Oracle's _VirtualBox Disk Image_ format


This seems wrong to me. It's not a format, it's a concept and a XAPI object.

OK, I remove it. I didn’t find convincing context or explanation for this one (that’s why I didn’t provide link)

stormi · 2026-05-27T10:31:53Z

+* VG:  [LVM's Volume Group](https://www.man7.org/linux/man-pages/man8/lvm.8.html#DESCRIPTION)
+* VHD: [_Virtual Hard Disk_ file format](https://en.wikipedia.org/wiki/VHD_(file_format)) ([specification](https://www.microsoft.com/en-us/download/details.aspx?id=23850))
+* VMDK: [_Virtual Machine Disk_ file format](https://en.wikipedia.org/wiki/VMDK) ([specification](https://github.com/libyal/libvmdk/blob/main/documentation/VMWare%20Virtual%20Disk%20Format%20(VMDK).asciidoc))
+* VM: [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine)


Also called domU or guest.

stormi · 2026-05-27T10:32:17Z

+* VHD: [_Virtual Hard Disk_ file format](https://en.wikipedia.org/wiki/VHD_(file_format)) ([specification](https://www.microsoft.com/en-us/download/details.aspx?id=23850))
+* VMDK: [_Virtual Machine Disk_ file format](https://en.wikipedia.org/wiki/VMDK) ([specification](https://github.com/libyal/libvmdk/blob/main/documentation/VMWare%20Virtual%20Disk%20Format%20(VMDK).asciidoc))
+* VM: [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine)
+* XAPI: [Xen Project Management API](/management/manage-at-scale/xo-api/)


It's XCP-ng's control plane.

The link is wrong.

freezed · 2026-05-27T15:30:11Z

Thanks for reviewing @stormi , I’ll proceed

freezed

Changes follow in commit

freezed · 2026-05-29T07:34:16Z

-* XCP - Xen Cloud Platform
-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"


I have no problems with previous version, it’s just that was the only term explained, all others has only acronym expansion. That’s why, in a manner of page consistance, I removed the explanation and mention an external link

freezed · 2026-05-29T07:36:39Z

-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"
+* DomU: Abbreviation for "[unprivileged domain](https://wiki.xenproject.org/wiki/DomU)" (no access to the hardware)


OK, that’s an important precision. I found this term when reading about dom0. I didn’t thought that it’s another name for a VM. I’ll add this precision

freezed · 2026-05-29T07:42:24Z

-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"
+* DomU: Abbreviation for "[unprivileged domain](https://wiki.xenproject.org/wiki/DomU)" (no access to the hardware)


That been said, DomU is only mentioned in docs/project/architecture.md page, so maybe it’s relevant to update it and change the term?

freezed · 2026-05-29T07:44:53Z

+* PIF: [Physical Interface](/project/architecture/#pifs)
+* PV: [Para-Virtualization](https://wiki.xenproject.org/wiki/Paravirtualization_(PV))
+* QCOW: [_QEMU Copy On Write_](https://en.wikipedia.org/wiki/Qcow), a disk image file format ([specification](https://www.qemu.org/docs/master/interop/qcow2.html))
+* RPU: [Rolling Pool Update](/management/updates/#from-xen-orchestra)


Fine to me. I’ll remove it.

freezed · 2026-05-29T07:50:43Z

+* PV: [Para-Virtualization](https://wiki.xenproject.org/wiki/Paravirtualization_(PV))
+* QCOW: [_QEMU Copy On Write_](https://en.wikipedia.org/wiki/Qcow), a disk image file format ([specification](https://www.qemu.org/docs/master/interop/qcow2.html))
+* RPU: [Rolling Pool Update](/management/updates/#from-xen-orchestra)
+* SMAPI: [Storage Manager API](https://github.com/xapi-project/xapi-storage)


The link mentioned relate explicitly to SMAPIv3

Xapi storage interface ("SMAPIv3")

If you can provide a suggestion, I’ll appreciated it (-;

freezed · 2026-05-29T07:52:37Z

+* SMAPI: [Storage Manager API](https://github.com/xapi-project/xapi-storage)
+* SR: [Storage Repository](/storage/)
+* VBD: [Virtual Block Device](https://docs.kernel.org/block/ublk.html)
+* VDI: Oracle's _VirtualBox Disk Image_ format


OK, I remove it. I didn’t find convincing context or explanation for this one (that’s why I didn’t provide link)

freezed · 2026-05-29T08:07:25Z

+* VHD: [_Virtual Hard Disk_ file format](https://en.wikipedia.org/wiki/VHD_(file_format)) ([specification](https://www.microsoft.com/en-us/download/details.aspx?id=23850))
+* VMDK: [_Virtual Machine Disk_ file format](https://en.wikipedia.org/wiki/VMDK) ([specification](https://github.com/libyal/libvmdk/blob/main/documentation/VMWare%20Virtual%20Disk%20Format%20(VMDK).asciidoc))
+* VM: [Virtual Machine](https://en.wikipedia.org/wiki/Virtual_machine)
+* XAPI: [Xen Project Management API](/management/manage-at-scale/xo-api/)


stormi · 2026-06-08T11:28:00Z

-* XCP-ng - XCP New Generation
+* CoW: [Copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write)
+* Dom0: Abbreviation for "[domain 0](https://wiki.xenproject.org/wiki/Dom0)"
+* DomU: Abbreviation for "[unprivileged domain](https://wiki.xenproject.org/wiki/DomU)", this is a lesser used term for <abbr title="Virtual Machine">VM</abbr>


That's not exactly what I said. WE use it less. Talk to xen developers, maybe they'll use it more, or use guest more.

Not sure to understand exactly the point, can you make a suggestion?

* DomU: In Xen terminology, a DomU (user domain) is what XCP-ng users would typically call a guest VM: a regular virtual machine running under the control of Dom0.

And a few more changes: - Use semicolons - Order entries alphabetically - Fix typo Signed-off-by: Frédéric Zind <frederic.zind@vates.tech>

This proposition aim to give a better solution to those: - xcp-ng#467 - xcp-ng#476 This is a first try: - a better integration on sidebar could be done - the sidebar is missing in the glossary page - the default glossary CSS is a bit wide on vertical range - and probably a lot of other things See plugin homepage: Signed-off-by: Frédéric Zind <frederic.zind@vates.tech>

) This proposition aim to give a better solution to those: - xcp-ng#467 - xcp-ng#476 See plugin homepage: https://github.com/mcclowes/docusaurus-plugin-glossary A term is kept only if it appears in the docs corpus (case-insensitive, whole-word, plural-aware). The native plugin behavior has been changed. Swizzle the plugin's GlossaryTerm theme component so the hover tooltip shows the term's full-name expansion (the abbreviation field, already present in glossary.json) before the definition, e.g. "VM - Virtual Machine - A guest operating system running on the hypervisor.". The upstream component renders term + definition only. The expansion is read from the abbreviation prop with a fallback to the plugin's global term data, and placeholder/empty expansions are skipped. See upstream PR: mcclowes/docusaurus-plugin-glossary#89 --- Signed-off-by: Frédéric Zind <frederic.zind@vates.tech> Co-authored-by: Bruno Verachten <bruno.verachten@vates.tech>

Terms has been curated and relates to the docs corpus (case-insensitive, whole-word, plural-aware). This proposition aim to give a better solution to those: - xcp-ng#467 - xcp-ng#476 Docusaurus «Glossary» plugin addition: Homepage: https://github.com/mcclowes/docusaurus-plugin-glossary The native plugin behavior has been changed. Swizzle the plugin's GlossaryTerm theme component so the hover tooltip shows the term's full-name expansion (the abbreviation field, already present in glossary.json) before the definition, e.g. "VM - Virtual Machine - A guest operating system running on the hypervisor.". The upstream component renders term + definition only. The expansion is read from the abbreviation prop with a fallback to the plugin's global term data, and placeholder/empty expansions are skipped. See: - upstream PR: mcclowes/docusaurus-plugin-glossary#89 - related issue: mcclowes/docusaurus-plugin-glossary#90 --- Co-authored-by: Bruno Verachten <bruno.verachten@vates.tech> Signed-off-by: Frédéric Zind <frederic.zind@vates.tech>

stormi · 2026-06-18T08:46:26Z

@freezed Always add a comment when closing a PR.

This PR was superseded by #486

freezed requested review from stormi and thomas-dkmt as code owners May 11, 2026 15:50

freezed marked this pull request as draft May 11, 2026 15:51

thomas-dkmt approved these changes May 12, 2026

View reviewed changes

thomas-dkmt requested changes May 12, 2026

View reviewed changes

freezed changed the title ~~Glossary review~~ Newbie review May 13, 2026

freezed force-pushed the glossary-review branch 5 times, most recently from 79be742 to 0f3765f Compare May 21, 2026 10:28

freezed changed the title ~~Newbie review~~ Glossary review May 21, 2026

freezed marked this pull request as ready for review May 21, 2026 10:29

freezed requested a review from thomas-dkmt May 21, 2026 10:33

Wescoeur reviewed May 21, 2026

View reviewed changes

Comment thread docs/appendix/glossary.md Outdated

freezed force-pushed the glossary-review branch 3 times, most recently from ce1e363 to b4da6b0 Compare May 22, 2026 13:43

thomas-dkmt approved these changes May 26, 2026

View reviewed changes

stormi requested changes May 27, 2026

View reviewed changes

stormi requested a review from thomas-dkmt May 27, 2026 10:34

freezed commented May 29, 2026

View reviewed changes

freezed force-pushed the glossary-review branch from b4da6b0 to bcb861b Compare May 29, 2026 08:18

freezed requested a review from stormi May 29, 2026 08:18

stormi reviewed Jun 8, 2026

View reviewed changes

Add more entries and related links

d94dff4

And a few more changes: - Use semicolons - Order entries alphabetically - Fix typo Signed-off-by: Frédéric Zind <frederic.zind@vates.tech>

freezed force-pushed the glossary-review branch from bcb861b to d94dff4 Compare June 9, 2026 08:14

freezed mentioned this pull request Jun 17, 2026

Add a glossary plugin with terms #486

Draft

freezed closed this Jun 18, 2026

Conversation

freezed commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thomas-dkmt left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freezed commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

freezed commented May 21, 2026

Uh oh!

Uh oh!

stormi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

freezed commented May 27, 2026

Uh oh!

freezed left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stormi commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

freezed commented May 11, 2026 •

edited

Loading

thomas-dkmt left a comment •

edited

Loading

freezed commented May 12, 2026 •

edited

Loading