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

[AKASHI Takahiro]

Tom,

Thank you for adding this valuable doc about CI.
I have a couple of comments from my real experience :)

On Fri, Dec 18, 2020 at 05:14:56PM -0500, Tom Rini wrote:
> 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>
> ---
>  doc/develop/ci_testing.rst | 45 ++++++++++++++++++++++++++++++++++++++
>  doc/develop/index.rst      |  1 +
>  2 files changed, 46 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..48dbec4a4452
> --- /dev/null
> +++ b/doc/develop/ci_testing.rst
> @@ -0,0 +1,45 @@
> +.. 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.

It would be nice to describe what is the difference between Azure and GitLab
in terms of test conditions/tested platforms if any.

> +
> +Azure Pipelines
> +---------------
> +
> +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 and submit a pull request against
> +https://github.com/u-boot/u-boot as this will trigger an Azure pipeline run.

To make a pull request, you will have to have your own repository which
was cloned from the original. I'm not sure that it is trivial for novice
users.

> +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
> +-------------------
> +
> +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.
> +
> +Docker container
> +----------------
> +
> +As previously states, both of the above pipelines build using the same Docker
> +container image.  This is maintained in the repository at
> +https://gitlab.denx.de/u-boot/gitlab-ci-runner and new images are made as
> +needed to support new tests or features.

It will be required to add an additional package(s) if you want to
use extra commands in your tests (especially in pytest).
It would be worth noting it here.

It may also be useful to mention about files like
  .azure-pipelines.yml
  .gitlab-ci.yml
  .travis.yml
and suggest that people should take a look at them so that we can
understand how those CI's work for U-Boot.

Thanks,
-Takahiro Akashi

> diff --git a/doc/develop/index.rst b/doc/develop/index.rst
> index 0a7e204b3438..d5619e8fce86 100644
> --- a/doc/develop/index.rst
> +++ b/doc/develop/index.rst
> @@ -7,6 +7,7 @@ Develop U-Boot
>  .. toctree::
>     :maxdepth: 2
>  
> +   ci_testing
>     coccinelle
>     commands
>     crash_dumps
> -- 
> 2.17.1
>