[at-spi2-core: 4/7] Document the image creation script

[Federico Mena Quintero <federico src gnome org>]

commit 1dd87fe487665586150c31302d0781072778bfe8
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Dec 16 14:31:43 2021 -0600

    Document the image creation script

 .gitlab-ci/README.md           | 56 +++++++++++++++++++++++++++++++++++++++---
 .gitlab-ci/opensuse.Dockerfile |  2 ++
 2 files changed, 55 insertions(+), 3 deletions(-)
---
diff --git a/.gitlab-ci/README.md b/.gitlab-ci/README.md
index f80669b5..9adfaac8 100644
--- a/.gitlab-ci/README.md
+++ b/.gitlab-ci/README.md
@@ -2,8 +2,10 @@
 
 Please see the general [documentation for at-spi2-core's Gitlab CI][ci-docs].
 
-This directory contains scripts which get called during a CI run, and
-utilities to maintain the CI infrastructure.
+This directory contains scripts which get called during a run of a CI
+pipeline, and utilities to maintain the CI infrastructure.
+
+## Scripts used during a run of a CI pipeline:
 
 * `run-tests.sh` - Runs the test suite and prints other diagnostics.
 
@@ -21,6 +23,54 @@ utilities to maintain the CI infrastructure.
 * `search-common-ancestor.sh` - Utility used from
   `run-style-check.sh`; finds a git branch point from the current
   commit.
-  
+
+## Utilities to maintain the CI infrastructure:
+
+To make pipelines fast, and avoid a lot of repeated downloads,
+at-spi2-core uses pre-built container images for CI pipelines, instead
+of using a stock image like opensuse/tumbleweed and then installing
+all the dependencies on top of it every time.
+
+The prebuilt images are stored here:
+https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry
+
+Instead of maintaining those images by hand with `docker` or `podman`
+commands, here is a little script (stolen from [glib][glib-ci]) to
+maintain them, which you can start exploring with `./run-docker.sh help`.
+
+This script knows how to build and upload images from Dockerfiles
+called `foo.Dockerfile`.  The image configurations we have:
+
+* `opensuse.Dockerfile` - starts with an opensuse/tumbleweed image and
+  installs the package dependencies for building at-spi2-core.
+
+If you are one of at-spi2-core's maintainers, you'll want to update
+the CI images periodically.  First, install `podman` and
+`podman-docker`.  Then, run this:
+
+```sh
+# "opensuse" in these commands indicates to use the opensuse.Dockerfile configuration
+
+./run-docker.sh build --base=opensuse      # builds the image, takes a while
+
+./run-docker.sh run --base=opensuse        # launch the container; poke around; see that it works
+
+./run-docker.sh push --base=opensuse       # push the image to registry.gitlab.gnome.org
+```
+
+The `build` subcommand creates an image named
+`registry.gitlab.gnome.org/gnome/at-spi2-core/opensuse/tumbleweed:latest`
+**that is only stored in your localhost**.
+
+The `run` subcommand launches a container with that image and gives
+you a shell prompt.  This is equivalent to `podman run`.
+
+The `push` subcommand takes that built image and uploads it to
+`registry.gitlab.gnome.org`.  It will then be visible from
+https://gitlab.gnome.org/GNOME/at-spi2-core/container_registry - the
+CI configuration in [`.gitlab-ci.yml`](../.gitlab-ci.yml) uses this
+image for the pipeline.
 
 [ci-docs]: ../devel-docs/gitlab-ci.md
+[container-registry-docs]: https://gitlab.gnome.org/help/user/packages/container_registry/index
+[glib-ci]: https://gitlab.gnome.org/GNOME/glib/-/tree/main/.gitlab-ci
diff --git a/.gitlab-ci/opensuse.Dockerfile b/.gitlab-ci/opensuse.Dockerfile
index 6bf3ef20..9fe6adfa 100644
--- a/.gitlab-ci/opensuse.Dockerfile
+++ b/.gitlab-ci/opensuse.Dockerfile
@@ -2,6 +2,8 @@
 #
 # This starts with an openSUSE Tumbleweed image, and installs the dependencies
 # for building and testing at-spi2-core.
+#
+# See README.md for documentation.
 
 FROM opensuse/tumbleweed:latest