[libvirt PATCH 09/10] docs: ci: Add a section on how to add a new platform to libvirt CI

[Erik Skultety]

Signed-off-by: Erik Skultety <eskultet at redhat.com>
---
 docs/ci.rst | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/ci.rst b/docs/ci.rst
index bef023c521..ea1b839eac 100644
--- a/docs/ci.rst
+++ b/docs/ci.rst
@@ -41,21 +41,60 @@ In case the integration test suite fails in our CI pipelines, a job artifact is
 generated containing Avocado logs, libvirt debug logs, and the latest traceback
 (if one was produced during a daemon's execution).
 
+Adding new OS platforms OR build pre-requisites
+===============================================
 
+Since all of the Dockerfiles libvirt uses for CI have been generated by ``lcitool``
+provided by the `libvirt-ci <https://gitlab.com/libvirt/libvirt-ci.git>`__ project,
+most relevant changes will need to be introduced to ``lcitool`` first.
 
+In cases where ``libvirt-ci`` does not know about the OS distro/build
+pre-requisite that is desired to be tested, proceed with the following:
 
+ * Send a mail regarding your desired build/coverage change to libvir-list
 
+   Note that in case you're looking into adding a new OS platform there are
+   limited CI compute resources available to libvirt, so the cost/benefit
+   trade-off of adding new OS distros needs to be considered and
+   is subject to a discussion on the mailing list.
 
+ * File an issue at https://gitlab.com/libvirt/libvirt-ci/-/issues
+   pointing to the libvir-list mail thread in the archives.
 
+   This alerts other people who might be interested in the work
+   to avoid duplication, as well as to get feedback from libvirt-ci
+   maintainers on any tips to ease the addition.
 
+Assuming there is agreement to the change you wish to make then
 
+ #. Fork the ``libvirt-ci`` project on gitlab
 
+ #.
+    * If adding a new OS distro, add metadata under
+      ``guests/lcitool/lcitool/ansible/group_vars/``
+      for the new OS distro. There might be code changes required if
+      the OS distro uses a package format not currently known. The
+      ``libvirt-ci`` maintainers can advise on this when the issue
+      is file. Edit the ``mappings.yml`` file to update all the existing package
+      entries, providing details of the new OS distro **OR**
 
+    * If **NOT** adding a new OS distro, simply edit the ``mappings.yml`` file
+      to provide a distro-agnostic mapping for the pre-requisite you're adding
 
+ #. Commit the ``mappings.yml`` change and submit a merge request to
+    the ``libvirt-ci`` project
 
+ #. CI pipeline will run to validate that the changes to ``mappings.yml``
+    are correct, by attempting to install the newly listed package on
+    all OS distributions supported by ``libvirt-ci``
 
+ #. Once the merge request is accepted, go back to libvirt and update the
+    ``ci/manifest.yml`` file to reflect your change
 
+ #. From the root of the libvirt git repository run
 
+::
 
+    $ lcitool manifest
 
 
-- 
2.36.1