Merge master into feature/perf and fix conflicts

.github/workflows/generate-and-build-sdks.yml

@@ -168,6 +168,7 @@ jobs:
         run: |
           dotnet test source/XenServerTest `
           --disable-build-servers `
+          -p:DefineConstants=BUILD_FOR_TEST `
           --verbosity=normal
 
       - name: Build C# SDK

.github/workflows/main.yml

@@ -1,8 +1,15 @@
 name: Build and test
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

.github/workflows/other.yml

@@ -1,8 +1,15 @@
 name: Build and test (other)
 
 on:
+  # When only Hugo docs change, this workflow is not required:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   schedule:
     # run daily, this refreshes the cache
     - cron: "13 2 * * *"

.github/workflows/shellcheck.yaml

@@ -2,6 +2,10 @@ name: ShellCheck
 
 on:
   pull_request:
+    # When only Hugo docs change, this workflow is not required:
+    paths-ignore:
+      - 'doc/**'
+      - '.github/workflows/hugo.yml'
   merge_group:
 
 concurrency:  # On new push, cancel old workflows from the same PR, branch or tag:

doc/README.md

@@ -1,9 +1,51 @@
-Quick start guide:
+# Quick start guide:
 
 - Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
+
+## Required software
+
+The docs use Hugo and the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn),
+an enhanced fork of the popular Hugo Learn theme.
+
+### Compatible versions
+
+Due to a number of gradual changes in Hugo and Relearn,
+the docs are currently only compatible with specific older versions of Hugo and Relearn.
+
+Hugo v0.121.0 to ~v0.127.0 (the current version of the Ubuntu `snap` is too recent)
+- Fixes to support newer versions are forthcoming.
+
+Hugo Relearn 5.24.0 (defined by a git tag in doc/go.mod)
+- Note: Hugo Relearn >= 5.25 currently trigger additional warnings due to deprecations.
+- Further updates fix this situation are forthcoming step by step.
+
+Hugo Relearn >= 5.24.0 and < 6.x are expected to work:
+- https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/5/index.html#5-24-0
+- Breaking changes in Relearn 6.0.0:
+  https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0
+
+## Installation
+
 - Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  You'll need Go as well: see https://go.dev/
-  - On Ubuntu 22.04 and older, use `sudo snap install hugo` to get the needed newer version of `hugo`.
+  You'll need to install Go as well: see https://go.dev/
+  - Hugo installation is described at https://gohugo.io/installation
+  - On Ubuntu 24.04, the version installed by `apt` works.
+  - On Ubuntu 22.04 and older:
+    - `apt-get install hugo` would install a version that is too old.
+    - `sudo snap install hugo` installs a too recent version
+
+  - To install Hugo from source, you need a recent `golang-1.2x` compiler:
+    - On Ubuntu 22.04, this can be done with:
+      ```bash
+      sudo apt install golang-1.23-go
+      # Add it to your path, assuming your .local/bin/ is early in your PATH:
+      ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
+      go version
+      go install github.com/gohugoio/hugo@v0.127.0
+      ```
+
+## Development
+
 - Run a local server: `hugo server`
 - Open a browser at http://127.0.0.1:1313/new-docs/
 - Add content to `doc/content/`:

doc/content/design/cpu-levelling-v2.md

@@ -29,7 +29,7 @@ The old XS 5.6-style Heterogeneous Pool feature that is based around hardware-le
 History
 =======
 
-- Original XS 5.6 design: [heterogeneous-pools](../heterogeneous-pools)
+- Original XS 5.6 design: [heterogeneous-pools](heterogeneous-pools)
 - Changes made in XS 5.6 FP1 for the DR feature (added CPUID checks upon migration)
 - XS 6.1: migration checks extended for cross-pool scenario
 

doc/content/design/integrated-gpu-passthrough/index.md

@@ -11,7 +11,7 @@ Introduction
 ------------
 
 Passthrough of discrete GPUs has been
-[available since XenServer 6.0]({{site.baseurl}}/xapi/design/gpu-passthrough.html).
+[available since XenServer 6.0](../gpu-passthrough.md).
 With some extensions, we will also be able to support passthrough of integrated
 GPUs.
 

doc/content/design/local-database.md

@@ -25,7 +25,7 @@ We propose to:
   this should reduce the number of RPCs across the network.
 
 In a later phase we can move to a completely
-[distributed database](../distributed-database).
+[distributed database](distributed-database/index).
 
 Replicating the database
 ------------------------

doc/content/design/multiple-cluster-managers.md

@@ -14,7 +14,7 @@ revision_history:
 Introduction
 ------------
 
-Xapi currently uses a cluster manager called [xhad](../../features/HA/HA.html). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
+Xapi currently uses a cluster manager called [xhad](../toolstack/features/HA/index). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
 
 1. modify the other software to take membership information from xapi; or
 2. modify xapi to take membership information from this other software.
@@ -70,4 +70,4 @@ The `xapi.conf` file will have a new field: `cluster-stack-root` which will have
 
 In `Pool.enable_ha` with `cluster_stack="foo"` we will verify that the subdirectory `<cluster-stack-root>/foo` exists. If it does not exist, then the call will fail with `UNKNOWN_CLUSTER_STACK`.
 
-Alternative cluster stacks will need to conform to the exact same interface as [xhad](../../features/HA/HA.html).
+Alternative cluster stacks will need to conform to the exact same interface as [xhad](../toolstack/features/HA).

doc/content/design/ocfs2/index.md

@@ -461,7 +461,7 @@ Summary of the impact on the admin
 
 OCFS2 is fundamentally a different type of storage to all existing storage
 types supported by xapi. OCFS2 relies upon O2CB, which provides
-[Host-level High Availability](../../../features/HA/HA.html). All HA implementations
+[Host-level High Availability](../../toolstack/features/HA/index). All HA implementations
 (including O2CB and `xhad`) impose restrictions on the server admin to
 prevent unnecessary host "fencing" (i.e. crashing). Once we have OCFS2 as
 a feature, we will have to live with these restrictions which previously only

doc/content/toolstack/features/DR/index.md

@@ -2,7 +2,7 @@
 title = "Disaster Recovery"
 +++
 
-The [HA](../HA/HA.html) feature will restart VMs after hosts have failed, but what
+The [HA](HA) feature will restart VMs after hosts have failed, but what
 happens if a whole site (e.g. datacenter) is lost? A disaster recovery
 configuration is shown in the following diagram: