Giovanni Mascellani : ci: Briefly document the CI setup.

[Alexandre Julliard]

Module: vkd3d
Branch: master
Commit: 367cf10cdcd5260c7c4991eae541d9e2cd53aaa9
URL:    https://gitlab.winehq.org/wine/vkd3d/-/commit/367cf10cdcd5260c7c4991eae541d9...

Author: Giovanni Mascellani 
Date:   Wed Aug 30 22:09:39 2023 +0200

ci: Briefly document the CI setup.

---

README        | 11 +++++++++++
 gitlab/README | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/README b/README
index 155f7de2..29f907de 100644
--- a/README
+++ b/README
@@ -82,3 +82,14 @@ commas or semicolons.
    conditions in tests.

* VKD3D_TEST_BUG - set to 0 to disable bug_if() conditions in tests.
+
+================
+Developing vkd3d
+================
+
+Development of vkd3d happens on the Wine GitLab instance
+(https://gitlab.winehq.org/wine/vkd3d/). Contributors are encouraged
+to submit their patches using the merge request tool.
+
+Each merge request is automatically tested with the GitLab CI
+system. See gitlab/README in the Git tree for more details.
diff --git a/gitlab/README b/gitlab/README
new file mode 100644
index 00000000..b04a3c8f
--- /dev/null
+++ b/gitlab/README
@@ -0,0 +1,42 @@
+=====================
+vkd3d testing scripts
+=====================
+
+These scripts are used by the GitLab CI feature to automatically run
+the vkd3d tests on each merge request.
+
+The CI target build-image, in the file image.yml, builds a Docker
+image based on Debian bookworm with all the packages required for
+testing, and uploads it to the GitLab container registry. The Docker
+script is in the file image.docker.
+
+The file build.yml contains the actual testing targets. Currently
+vkd3d is tested on Linux x86-64, with two different Vulkan drivers
+(both from Mesa): llvmpipe (a software implementation) and RADV (a
+hardware implementation backed by an AMD GPU). The testing logs are
+available as CI artifacts.
+
+Some custom runner configuration is required in order to run the tests
+on an AMD GPU. Specifically, a runner tagged with `amd-gpu' must be
+available with the following features:
+
+ * of course a sufficiently recent AMD GPU must be available to the
+   host;
+
+ * the host kernel must have the appropriate driver and firmware
+   installed;
+
+ * the runner must forward the DRI nodes to the guest; this can be
+   configured by adding the line
+
+     devices = ["/dev/dri"]
+
+   to the relevant [runners.docker] section in the config.toml file;
+
+ * the DRI render nodes must be readable and writable by GID 800,
+   either because they belong to that group (e.g. because the group
+   `render', which typically owns those files, has GID 800) or via a
+   FS ACL; such stipulation is needed because in Debian group `render'
+   is created dynamically, therefore has no predictable GID: the use
+   of a fixed GID enables the guest system to be set up so that the
+   user running the tests can access the render nodes.