[ovirt-devel] [ANNOUNCE] Introducing STDCI V2

The CI team is thrilled to announce the general availability of the second version of the oVirt CI standard. Work on this version included almost a complete rewrite of the CI backend. The major user-visible features are: - Project maintainers no longer need to maintain YAML in the ‘jenkins’ repository. Details that were specified there, including targeted distributions, architectures and oVirt versions should now be specified in a YAML file under the project’s own repository (In a different syntax). - We now support “sub stages” which provide the ability to run multiple different scripts in parallel within the same STDCI stage. There is also a conditional syntax which allows controlling which scripts get executed according to which files were changed in the patch being tested. - The STDCI script file names and locations can now be customized via the above mentioned YAML file. This means that for e.g. using the same script for different stages can now be done by assigning it to the stages in the YAML file instead of by using symlinks. Inspecting job results in STDCI V2 ---------------------------------- As already mentioned, the work on STDCI V2 consisted of a major rewrite of the CI backend, one of the changes made is switching from using multiple “FreeStyle” type jobs per project to just two (pre-merge and post-merge) pipeline jobs. This has implications for the way job results are to be inspected. Since all the different parallel tasks now happen within the same job, looking at the job output can be rather confusing as it includes the merged output of all the tasks. Instead, the “Blue Ocean” view should be used. The “Blue Ocean” view displays a graphical layout of the job execution allowing one to quickly learn which parts of the job failed. It also allows drilling down and viewing the logs of individual parts of the job. Apart from using the “Blue Ocean” view, job logs are also stored as artifact files. The ‘exported-artifacts’ directory seen in the job results will now include different subdirectories for the different parts of the job. Assuming we have a ‘check-patch’ stage script running on ‘el7/x86_64’, we can find its output under ‘exported-artifacts’ in: check-patch.el7.x86_64/mock_logs/script/stdout_stderr.log Any additional artifacts generated by the script would be present in the ‘check-patch.el7.x86-64’ directory as well. I have a CI YAML file in my project already, is this really new? ---------------------------------------------------------------- We’ve been working on this for a while, and occasionally introduced V2 features into individual projects as needed. In particular, our GitHub support was always based on STDCI V2 code, so all GitHub projects (except Lago, which is ‘special’…) are already using STDCI V2. A few Gerrit-based projects have already been converted to V2 as well as part of our efforts to test and debug the V2 code. Most notably, the “OST” and “Jenkins” projects have been switched, although they are running the STDCI V1 jobs as well for the time being. What is the process for switching my project to STDCI V2? --------------------------------------------------------- The CI team is going to proactively work with project maintainers to switch them to V2. The process for switching is as follows: - Send a one-line patch to the ‘jenkins’ repo to enable the V2 jobs for the project - at this point the V2 jobs will run side-by-side with the V1 jobs, and will execute the STDCI scripts on el7/x86_64. - Create an STDCI YAML file to define the target distributions, architectures and oVirt versions for the project. (See below for a sample file that would be equivalent to what many projects have defined in V1 currently). As soon as a patch with the new YAML file is submitted to the project, the V2 job will parse it and follow the instructions in it. This allows for an easy verification of the file functionality in CI. - Remove the STDCI V1 job configuration from the ‘jenkins’ repo. This should be the last patch project maintainers have to send to the ‘jenkins’ repo. What does the new YAML file look like? -------------------------------------- We defined multiple optional names for the file, so that each project owner can choose which name seems most adequate. The following names can be used: - stdci.yaml - automation.yaml - ovirtci.yaml A dot (.) can also optionally be added at the beginning of the file name to make the file hidden, the file extension could also be “yml”. If multiple matching files exist in the project repo, the first matching file according to the order listed above will be used. The file conforms to the YAML syntax. The key names in the file are case-agnostic, and hyphens (-) underscores (_) and spaces ( ) in key names are ignored. Additionally we support multiple forms of the same word so you don’t need to remember if the key should be ‘distro’, ‘distros’, ‘distributions’, ‘operating-systems’ or ‘OperatingSystems’ as all these forms (and others) will work and mean the same thing. To create complex test/build matrices, ‘stage’, ‘distribution’, ‘architecture’ and ‘sub-stage’ definitions can be nested within one another. We find this to be more intuitive than having to maintain tedious ‘exclude’ lists as was needed in V1. Here is an example of an STDCI V2 YAML file that is compatible with the current master branch V1 configuration of many oVirt projects: --- Architectures: - x86_64: Distributions: [ "el7", "fc27" ] - ppc64le: Distribution: el7 - s390x: Distribution: fc27 Release Branches: master: ovirt-master Note: since the file is committed into the project’s own repo, having different configuration for different branches can be done by simply having different files in the different branches, so there is no need for a big convoluted file to configure all branches. Since the above file does not mention stages, any STDCI scripts that exists in the project repo and belong to a particular stage will be run on all specified distribution and architecture combinations. Since it is sometimes desired to run ‘check-patch.sh’ on less platforms then build-artifacts for example, a slightly different file would be needed: --- Architectures: - x86_64: Distributions: [ “el7”, “fc27” ] - ppc64le: Distribution: el7 - s390x: Distribution: fc27 Stages: - check-patch: Architecture: x86_64 Distribution: el7 - build-artifacts Release Branches: master: ovirt-master The above file makes ‘check-patch’ run only on el7/x86_64, while build-artifacts runs on all platforms specified and check-merged would not run at all because it is not listed in the file. Great efforts have been made to make the file format very flexible but intuitive to use. Additionally there are many defaults in place to allow specifying complex behaviours with very brief YAML code. For further details about the file format, please see the documentation linked below. About the relation between STDCI V2 and the change-queue -------------------------------------------------------- In STDCI V1 the change queue that would run the OST tests and release a given patch was determined by looking at the “version” part of the name of the project’s build-artifacts jobs that got invoked for the patch. This was confusing for people as most people understood “version” to mean the internal version for their own project rather then the oVirt version. In V2 we decided to be more explicit and simply include a map from branches to change queues in the YAML configuration under the “release-branches” option, as can be seen in the examples above. We also chose to no longer allow specifying the oVirt version as a shorthand for the equivalent queue name (E.g specifying ‘4.2’ instead of ‘ovirt-4.2’), this should reduce the chance for confusing between project versions and queue names, and also allows us to create and use change queues for projects that are not oVirt. A project can choose not to include a “release-branches” option, in which case its patches will not get submitted to any queues. Further information ------------------- The documentation for STDCI can be found at [1]. The documentation update for V2 are still in progress and expected to be merged soon. In the meatine, the GitHub-specific documentation [2] already provides a great deal of information which is relevant for V2. [1]: http://ovirt-infra-docs.readthedocs.io/en/latest/CI/Build_and_test_standards [2]: http://ovirt-infra-docs.readthedocs.io/en/latest/CI/Using_STDCI_with_GitHub --- Barak Korren RHV DevOps team , RHCE, RHCi Red Hat EMEA redhat.com | TRIED. TESTED. TRUSTED. | redhat.com/trusted