diff options
Diffstat (limited to 'docs/devel')
| -rw-r--r-- | docs/devel/testing.rst | 76 |
1 files changed, 45 insertions, 31 deletions
diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst index e10c47b5a7..362a26698b 100644 --- a/docs/devel/testing.rst +++ b/docs/devel/testing.rst @@ -429,49 +429,61 @@ using the ``lcitool`` program provided by the ``libvirt-ci`` project: https://gitlab.com/libvirt/libvirt-ci -In that project, there is a ``mappings.yml`` file defining the distro native -package names for a wide variety of third party projects. This is processed -in combination with a project defined list of build pre-requisites to determine -the list of native packages to install on each distribution. This can be used -to generate dockerfiles, VM package lists and Cirrus CI variables needed to -setup build environments across OS distributions with a consistent set of -packages present. - -When preparing a patch series that adds a new build pre-requisite to QEMU, -updates to various lcitool data files may be required. +``libvirt-ci`` contains an ``lcitool`` program as well as a list of +mappings to distribution package names for a wide variety of third +party projects. ``lcitool`` applies the mappings to a list of build +pre-requisites in ``tests/lcitool/projects/qemu.yml``, determines the +list of native packages to install on each distribution, and uses them +to generate build environments (dockerfiles and Cirrus CI variable files) +that are consistent across OS distribution. Adding new build pre-requisites ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When preparing a patch series that adds a new build +pre-requisite to QEMU, the prerequisites should to be added to +``tests/lcitool/projects/qemu.yml`` in order to make the dependency +available in the CI build environments. + In the simple case where the pre-requisite is already known to ``libvirt-ci`` -the following steps are needed +the following steps are needed: * Edit ``tests/lcitool/projects/qemu.yml`` and add the pre-requisite * Run ``make lcitool-refresh`` to re-generate all relevant build environment manifests -In some cases ``libvirt-ci`` will not know about the build pre-requisite and -thus some extra preparation steps will be required first +It may be that ``libvirt-ci`` does not know about the new pre-requisite. +If that is the case, some extra preparation steps will be required +first to contribute the mapping to the ``libvirt-ci`` project: * Fork the ``libvirt-ci`` project on gitlab - * Edit the ``mappings.yml`` change to add an entry for the new build - prerequisite, listing its native package name on as many OS distros - as practical. + * Add an entry for the new build prerequisite to + ``lcitool/facts/mappings.yml``, listing its native package name on as + many OS distros as practical. Run ``python -m pytest --regenerate-output`` + and check that the changes are correct. - * Commit the ``mappings.yml`` change and submit a merge request to - the ``libvirt-ci`` project, noting in the description that this - is a new build pre-requisite desired for use with QEMU + * Commit the ``mappings.yml`` change together with the regenerated test + files, and submit a merge request to the ``libvirt-ci`` project. + Please note in the description that this is a new build pre-requisite + desired for use with QEMU. * 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 QEMU and update - the ``libvirt-ci`` submodule to point to a commit that contains - the ``mappings.yml`` update. + the ``tests/lcitool/libvirt-ci`` submodule to point to a commit that + contains the ``mappings.yml`` update. Then add the prerequisite and + run ``make lcitool-refresh``. + +For enterprise distros that default to old, end-of-life versions of the +Python runtime, QEMU uses a separate set of mappings that work with more +recent versions. These can be found in ``tests/lcitool/mappings.yml``. +Modifying this file should not be necessary unless the new pre-requisite +is a Python library or tool. Adding new OS distros @@ -498,18 +510,20 @@ Assuming there is agreement to add a new OS distro then * Fork the ``libvirt-ci`` project on gitlab - * 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. + * Add metadata under ``lcitool/facts/targets/`` 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 filed. - * Edit the ``mappings.yml`` change to update all the existing package - entries, providing details of the new OS distro + * Edit the ``lcitool/facts/mappings.yml`` change to add entries for + the new OS, listing the native package names for as many packages + as practical. Run ``python -m pytest --regenerate-output`` and + check that the changes are correct. - * Commit the ``mappings.yml`` change and submit a merge request to - the ``libvirt-ci`` project, noting in the description that this - is a new build pre-requisite desired for use with QEMU + * Commit the changes to ``lcitool/facts`` and the regenerated test + files, and submit a merge request to the ``libvirt-ci`` project. + Please note in the description that this is a new build pre-requisite + desired for use with QEMU * CI pipeline will run to validate that the changes to ``mappings.yml`` are correct, by attempting to install the newly listed package on |