[PATCH] doc: Add basic information about running CI tests

[Tom Rini]

Start out by documenting general expectations on when CI is run, how
anyone can run Azure pipelines, and how GitLab CI pipelines can be run.

Signed-off-by: Tom Rini <trini at konsulko.com>
---
Changes in v3:
- Really address all of the feedback.

Changes in v2:
- Address some of Akashi-san's feedback
---
 doc/develop/ci_testing.rst | 70 ++++++++++++++++++++++++++++++++++++++
 doc/develop/index.rst      |  1 +
 2 files changed, 71 insertions(+)
 create mode 100644 doc/develop/ci_testing.rst

diff --git a/doc/develop/ci_testing.rst b/doc/develop/ci_testing.rst
new file mode 100644
index 000000000000..b9a9a516c1e6
--- /dev/null
+++ b/doc/develop/ci_testing.rst
@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Continuous Integration testing
+==============================
+
+All changes require passing our continuous integration tests prior to being
+merged in to mainline.  To help facilitate merges being accepted quickly,
+custodians are encouraged but not required to run a pipeline prior to sending a
+pull request.  Individual developers submitting significant or widespread
+changes are encouraged to run a pipeline themselves prior to posting.
+
+In order to make this process as easy as possible, the ability to run a CI
+pipeline is provided in both Azure and GitLab.  Both of these pipelines perform
+their Linux build jobs on the same Docker container image and to cover the same
+platforms.  In addition, Azure is also used to confirm that our host tools can
+be built with mingw to run on Windows.
+
+Each of the pipelines is written in such as way as to be a "world build" style
+test and as such we try and build all possible platforms.  In addition, for all
+platforms that support being run in QEMU we run them in QEMU and use our pytest
+suite.  See :doc:`py_testing` for more information about those tests.
+
+Azure Pipelines
+---------------
+
+This pipeline is defined in the top-level ``.azure-pipelines.yml`` file.
+Currently there are two ways to run a Microsoft Azure Pipeline test for U-Boot.
+
+The first way is to create an account with Microsoft at
+https://azure.microsoft.com/en-us/services/devops/ and then use the
+``.azure-pipelines.yml`` file in the U-Boot repository as the pipeline
+description.
+
+The second way is to use GitHub.  This requires a GitHub account
+and to fork the repository at https://github.com/u-boot/u-boot and to then
+submit a pull request as this will trigger an Azure pipeline run.  Clicking on
+your pull request on the list at https://github.com/u-boot/u-boot/pulls and
+then the "Checks" tab will show the results.
+
+GitLab CI Pipelines
+-------------------
+
+This pipeline is defined in the top-level ``.gitlab-ci.yml`` file.  Currently,
+we support running GitLab CI pipelines only for custodians, due to the
+resources the project has available.  For Custodians, it is a matter of
+enabling the pipeline feature in your project repository following the standard
+GitLab documentation.  For non-custodians, the pipeline itself is part of the
+tree and should be able to be used on any GitLab instance, with whatever
+runners you are able to provide.  While it is intended to be able to run this
+pipeline on the free public instances provided at https://gitlab.com/ a problem
+with our squashfs tests currently prevents this.
+
+Docker container
+----------------
+
+As previously stated, both of the above pipelines build using the same Docker
+container image.  This is maintained in the U-Boot source tree at
+``tools/docker/Dockerfile`` and new images are made as needed to support new
+tests or features.  This file needs to be updated whenever adding new external
+tool requirements to tests.
+
+Customizing CI
+--------------
+
+As noted above, the CI pipelines perform a world build.  While this is good for
+overall project testing, it can be less useful for testing specific cases or
+developing features.  In that case, it can be useful as part of your own
+testing cycle to edit these pipelines in separate local commits to pair them
+down to just the jobs you're interested in.  These changes must be removed
+prior to submission.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 54e14dd77b5e..3c0f2da44318 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -9,6 +9,7 @@ Implementation
 .. toctree::
    :maxdepth: 1
 
+   ci_testing
    commands
    driver-model/index
    global_data
-- 
2.17.1