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

[Daniel P. Berrangé]

On Tue, Jul 12, 2022 at 02:44:41PM +0200, Erik Skultety wrote:
> 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.

I feel it'd be sufficient to just have the libvirt-ci issue, as all the
maintainers interested in CI pay attention to that, but no big deal
either way.

> +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

I feel like these bits probably ought to be put in a doc like;

  $libvirt-ci.git/docs/new-distro.rst

and just link to the git msater of that doc from here. GitLab renders the
RST nicely enough, and it'd be nice to have these steps in a self-contained
doc, so I can point QEMU maintainers to it too.

>  
> + #. From the root of the libvirt git repository run
>  
> +::
>  
> +    $ lcitool manifest

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|