GNOME.org
 

[at-spi2-core: 2/7] Document the CI pipeline in devel-docs/gitlab-ci.md


commit 3218fa05e503cf05b8a1ce6c2190a39eb5bbc54a
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Dec 14 18:55:42 2021 -0600

    Document the CI pipeline in devel-docs/gitlab-ci.md

 .gitlab-ci.yml          |  47 +++++++++++++--
 devel-docs/gitlab-ci.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 192 insertions(+), 6 deletions(-)
---
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a5f371ab..16d1790c 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,5 +1,14 @@
+# Continuous Integration configuration for at-spi2-core
+#
+# For documentation on how this works, see devel-docs/gitlab-ci.md
+#
+# Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/
+#
+# Introduction to Gitlab CI: https://docs.gitlab.com/ee/ci/quick_start/index.html
+
 variables:
 
+# Stages in the CI pipeline in which jobs will be run
 stages:
 #  - style-check
   - build
@@ -7,6 +16,10 @@ stages:
   - docs
   - deploy
 
+# Base definition for jobs.
+#
+# We have the package dependencies to install on top of a stock opensuse/tumbleweed image,
+# and the rules for when to run each job (on merge requests and on personal branches).
 .only-default:
   variables:
     PROJECT_DEPS:
@@ -33,6 +46,10 @@ stages:
   except:
     - tags
 
+# C coding style checker.
+#
+# Disabled for now, since we need to decide to reindent all the code first.
+#
 # style-check-diff:
 #   extends: .only-default
 #   image: fedora:latest
@@ -41,9 +58,11 @@ stages:
 #     - dnf install -y clang-tools-extra curl diffutils git
 #     - sh -x ./.gitlab-ci/run-style-check.sh
 
-# Recipe for setting up the build
+# Template for setting up build jobs.
+#
+# Depends on these variables:
 # @PROJECT_DEPS: the dependencies of the project (on openSUSE)
-# @MESON_VERSION: the version of Meson required by the project
+# @EXTRA_DEPS: Extra dependencies specific to each job (e.g. lcov for the coverage job).
 .build-setup:
   image: opensuse/tumbleweed
   extends: .only-default
@@ -51,9 +70,11 @@ stages:
     - zypper refresh
     - zypper install -y ${PROJECT_DEPS} ${EXTRA_DEPS}
 
-# Default build recipe
+# Template for the default build recipe.
+#
+# Depends on these variables:
 # @PROJECT_DEPS: the dependencies of the project (on openSUSE)
-# @MESON_VERSION: the version of Meson required by the project
+# @EXTRA_DEPS: Extra dependencies specific to each job (e.g. lcov for the coverage job).
 # @MESON_EXTRA_FLAGS: extra arguments for the meson setup invocation
 .build-default:
   image: opensuse/tumbleweed
@@ -77,7 +98,6 @@ stages:
 
 # Inherit to build the API reference via gi-docgen
 # @PROJECT_DEPS: the dependencies of the project (on Fedora)
-# @MESON_VERSION: the version of Meson required by the project
 # @MESON_EXTRA_FLAGS: extra arguments for the meson setup invocation
 # @DOCS_FLAGS: doc-related arguments for the meson setup invocation
 # @DOCS_PATH: the docs output directory under the build directory
@@ -103,6 +123,9 @@ stages:
 #     paths:
 #       - ${CI_PROJECT_NAME}-docs.tar
 
+# Build and run the test suite.
+#
+# Look at .build-default for where the artifacts are stored (build/test logs, built binaries).
 opensuse-x86_64:
   extends: .build-default
   stage: build
@@ -110,6 +133,9 @@ opensuse-x86_64:
   variables:
     MESON_EXTRA_FLAGS: "--buildtype=debug" # -Dwerror=true
 
+# Run static analysis on the code.
+#
+# The logs are part of the compilation stderr.
 static-scan:
   extends: .build-setup
   stage: analysis
@@ -128,6 +154,7 @@ static-scan:
     paths:
       - "_scan_build/meson-logs/scanbuild"
 
+# Build and run with address sanitizer (asan).
 asan-build:
   extends: .build-setup
   stage: analysis
@@ -148,6 +175,9 @@ asan-build:
       - "_asan_build/meson-logs"
   allow_failure: true
 
+# Run the test suite and extract code coverage information.
+#
+# See the _coverage/ artifact for the HTML report.
 coverage:
   extends: .build-setup
   stage: analysis
@@ -175,6 +205,8 @@ coverage:
       - "_coverage"
   allow_failure: true
 
+# Build the reference documentation.
+#
 # reference:
 #   stage: docs
 #   needs: []
@@ -200,7 +232,10 @@ coverage:
 #     MESON_VERSION: "0.55.3"
 #     DOCS_FLAGS: -Dgtk_doc=true
 #     DOCS_PATH: doc/libgweather-4.0
-# 
+#
+#
+# Publish the generated HTML reference documentation.
+#
 # pages:
 #   stage: deploy
 #   needs: ['reference']
diff --git a/devel-docs/gitlab-ci.md b/devel-docs/gitlab-ci.md
new file mode 100644
index 00000000..333f6c86
--- /dev/null
+++ b/devel-docs/gitlab-ci.md
@@ -0,0 +1,151 @@
+# Gitlab Continuous Integration (CI) for at-spi2-core
+
+Summary: make the robots set up an environment for running the test
+suite, run it, and report back to us.
+
+If you have questions about the CI, mail federico gnome org, or [file
+an issue](https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues) and
+mention `@federico` in it.
+
+Table of contents:
+
+[[_TOC_]]
+
+## Quick overview
+
+By having a [`.gitlab-ci.yml`](../.gitlab-ci.yml) file in the toplevel
+directory of a project, Gitlab knows that it must run a continuous
+integration pipeline when certain events occur, for example, when
+someone creates a merge request, or pushes to a branch.
+
+What's a pipeline?  It is an automated version of the following.
+Running the test suite for at-spi2-core involves some repetitive
+steps:
+
+* Create a pristine and minimal environment for testing, without all the random
+  gunk from one's development system.  Gitlab CI uses Linux containers,
+  with pre-built operating system images in the [Open Container
+  Initiative][OCI] format — this is what Docker, Podman, etc. all use.
+
+* Install the build-time dependencies (gcc, meson, libfoo-devel,
+  etc.), the test-time dependencies (dbus-daemon, etc.) in that
+  pristine environment, as well as special tools (lcov, libasan,
+  clang-tools).
+
+* Run the build and install it, and run the test suite.
+
+* Run variations of the build and test suite with other tools — for
+  example, using static analysis during compilation, or with address
+  sanitizer (asan), or with a code coverage tool.  Gitlab can collect
+  the analysis results of each of these tools and present them as part
+  of the merge request that is being evaluated.  It also lets
+  developers obtain those useful results without dealing with a lot of
+  fiddly tools on their own computers.
+  
+Additionally, on each pipeline run we'd like to do extra repetitive
+work like building the reference documentation, and publishing it on a
+web page.
+
+The `.gitlab-ci.yml` file defines the CI pipeline, the jobs it will
+run (build/test, coverage, asan, static-scan, etc.), and the locations
+where each job's artifacts will be stored.
+
+What's an artifact or a job?  Read on!
+
+## A little glossary
+
+**Pipeline** - A collection of **jobs**, which can be run in parallel
+or sequentially.  For example, a pair of "build" and "test" jobs would
+need to run sequentially, but maybe a "render documentation" job can
+run in parallel with them.  Similarly, "build" jobs for various
+distributions or configurations could be run in parallel.
+
+**Job** - Think of it as running a shell script within a container.
+It can have input from other previous jobs: if you have separate
+"build" and "test" jobs, then the "build" job will want to keep around
+its compiled artifacts so that the "test" job can use them.  It can
+provide output artifacts that can be stored for human perusal, or for
+use by other jobs.
+
+**Artifact** - Something produced from a job.  If your job compiles
+binaries, those binaries could be artifacts if you decide to keep them
+around for use later.  A documentation job can produce HTML artifacts
+from the rendered documentation.  A code coverage job will produce a
+coverage report artifact.
+
+**Runner** - An operating system setup for running jobs.
+Gitlab.gnome.org provides runners for Linux, BSD, Windows, and MacOS.
+For example. the Linux runners let you use any OCI image, so you can
+test on openSUSE, Fedora, a custom distro, etc.  You don't normally
+need to be concerned with runners; Gitlab assigns the shared runners
+automatically to your pipeline.
+
+**Container** - You can think of it as a chroot with extra isolation,
+or a lightweight virtual machine.  Basically, the Linux kernel can
+isolate groups of processes in control groups (cgroups).  Each cgroup
+can have a different view of the file system, as if you had a
+different chroot for each cgroup.  Cgroups can be isolated to be in
+their own PID namespace, so running "ps" in the container will not
+show all the processes in the system, but only those inside the
+container's cgroup.  File system overlays allow you to have read-only
+images for the operating system (the OCI images we talked about above)
+plus a read-write overlay that is kept around only during the lifetime
+of a container, or persistently if one wants.  For Gitlab CI one does
+not need to deal with containers directly, but keep in mind that your
+jobs will run inside a container, which is more limited than e.g. a
+shell session on a graphical, development machine.
+
+## The CI pipeline for at-spi2-core
+
+The `.gitlab-ci.yml` file is a more-or-less declarative description
+the CI pipeline, with some `script` sections which are imperative
+commands to actually *do stuff*.
+
+Jobs are run in `stages`, and the names of the stages are declared
+near the beginning of the YAML file.  The stage names are arbitrary;
+the ones here follow some informal GNOME conventions.
+
+Jobs are declared at the toplevel of the YAML file, and they are
+distinguished from other declarations by having a container `image`
+declared for them, as well as a `script` to execute.
+
+Many jobs need exactly the same kind of setup (same container images,
+mostly same package dependencies), so they use `extends:` to use a
+declared template with all that stuff instead of redeclaring it each
+time.  In our configuration, the `.only-default` template has the
+`PROJECT_DEPS`, with the dependencies that most jobs need.  The
+`.build-setup` template is for the analysis jobs, and it lets them
+declare `EXTRA_DEPS` as an environment variable with the names of
+extra dependencies: for example, the coverage job puts `lcov` in
+`EXTRA_DEPS`.
+
+The `build` stage has these jobs:
+
+* `opensuse-x86_64` - Extends the `.build-default` rule,
+  builds/installs the code, and runs the tests.  Generally this is the
+  job that one cares about during regular development.
+
+The `analysis` stage has these jobs:
+
+* `static-scan` - Runs static analysis during compilation, which
+  performs interprocedural analysis to detect things like double
+  `free()` or uninitialized struct fields across functions.
+  
+* `asan-build` - Builds and runs with Address Sanitizer (libasan).
+
+* `coverage` - Instruments the build to get code coverage information,
+  and runs the test suite to see how much of the code it manages to
+  exercise.  This is to see which code paths may be untested
+  automatically, and to decide which ones would require manual
+  testing, or refactoring to allow automated testing.
+
+As of 2021/Dec/15 there are some commented-out jobs to generate
+documentation and publish it; this needs to be made to work.
+
+## References
+
+Full documentation for Gitlab CI: https://docs.gitlab.com/ee/ci/
+
+Introduction to Gitlab CI: https://docs.gitlab.com/ee/ci/quick_start/index.html
+
+[OCI]: https://opencontainers.org/
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]