doc/develop/ci_testing.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 Continuous Integration testing
   4 ==============================
   5
   6 All changes require passing our continuous integration tests prior to being
   7 merged in to mainline.  To help facilitate merges being accepted quickly,
   8 custodians are encouraged but not required to run a pipeline prior to sending a
   9 pull request.  Individual developers submitting significant or widespread
  10 changes are encouraged to run a pipeline themselves prior to posting.
  11
  12 In order to make this process as easy as possible, the ability to run a CI
  13 pipeline is provided in both Azure and GitLab.  Both of these pipelines perform
  14 their Linux build jobs on the same Docker container image and to cover the same
  15 platforms.  In addition, Azure is also used to confirm that our host tools can
  16 be built with mingw to run on Windows.
  17
  18 Each of the pipelines is written in such as way as to be a "world build" style
  19 test and as such we try and build all possible platforms.  In addition, for all
  20 platforms that support being run in QEMU we run them in QEMU and use our pytest
  21 suite.  See :doc:`py_testing` for more information about those tests.
  22
  23 Azure Pipelines
  24 ---------------
  25
  26 This pipeline is defined in the top-level ``.azure-pipelines.yml`` file.
  27 Currently there are two ways to run a Microsoft Azure Pipeline test for U-Boot.
  28
  29 The first way is to create an account with Microsoft at
  30 https://azure.microsoft.com/en-us/services/devops/ and then use the
  31 ``.azure-pipelines.yml`` file in the U-Boot repository as the pipeline
  32 description.
  33
  34 The second way is to use GitHub.  This requires a GitHub account
  35 and to fork the repository at https://github.com/u-boot/u-boot and to then
  36 submit a pull request as this will trigger an Azure pipeline run.  Clicking on
  37 your pull request on the list at https://github.com/u-boot/u-boot/pulls and
  38 then the "Checks" tab will show the results.
  39
  40 GitLab CI Pipelines
  41 -------------------
  42
  43 This pipeline is defined in the top-level ``.gitlab-ci.yml`` file.  Currently,
  44 we support running GitLab CI pipelines only for custodians, due to the
  45 resources the project has available.  For Custodians, it is a matter of
  46 enabling the pipeline feature in your project repository following the standard
  47 GitLab documentation.  For non-custodians, the pipeline itself is part of the
  48 tree and should be able to be used on any GitLab instance, with whatever
  49 runners you are able to provide.  While it is intended to be able to run this
  50 pipeline on the free public instances provided at https://gitlab.com/ a problem
  51 with our squashfs tests currently prevents this.
  52
  53 Docker container
  54 ----------------
  55
  56 As previously stated, both of the above pipelines build using the same Docker
  57 container image.  This is maintained in the U-Boot source tree at
  58 ``tools/docker/Dockerfile`` and new images are made as needed to support new
  59 tests or features.  This file needs to be updated whenever adding new external
  60 tool requirements to tests.
  61
  62 Customizing CI
  63 --------------
  64
  65 As noted above, the CI pipelines perform a world build.  While this is good for
  66 overall project testing, it can be less useful for testing specific cases or
  67 developing features.  In that case, it can be useful as part of your own
  68 testing cycle to edit these pipelines in separate local commits to pair them
  69 down to just the jobs you're interested in.  These changes must be removed
  70 prior to submission.