Merge branch 'master' into feature/tokens

1 files changed, 45 insertions, 36 deletions

diff --git a/design-documents/044-ci-system.rst b/design-documents/044-ci-system.rst
index e777f345..e38632c0 100644
--- a/design-documents/044-ci-system.rst
+++ b/design-documents/044-ci-system.rst
@@ -6,7 +6,7 @@ Summary
 
 This documents describes Taler's CI system based on Buildbot.
 
-This document uses `RFC 2119 <https://tools.ietf.org/html/rfc2119>`_  
+This document uses `RFC 2119 <https://tools.ietf.org/html/rfc2119>`_
 keywords throughout.
 
 Motivation
@@ -43,27 +43,28 @@ Example directory structure:
 
 ::
 
-  ci
-  ├── ci.sh
-  ├── Containerfile
-  └── jobs
-      ├── 0-codespell
-      │   ├── config.ini
-      │   ├── dictionary.txt
-      │   └── job.sh
-      ├── 1-build
-      │   ├── build.sh
-      │   └── job.sh
-      └── 2-docs
-          ├── docs.sh
-          └── job.sh
-  
-Job directories **MUST** follow this pattern: 
-``<repo_root>/ci/jobs/<n-job_name>/``
+  contrib
+  └── ci
+      ├── ci.sh
+      ├── Containerfile
+      └── jobs
+          ├── 0-codespell
+          │   ├── config.ini
+          │   ├── dictionary.txt
+          │   └── job.sh
+          ├── 1-build
+          │   ├── build.sh
+          │   └── job.sh
+          └── 2-docs
+              ├── docs.sh
+              └── job.sh
+
+Job directories **MUST** follow this pattern:
+``<repo_root>/contrib/ci/jobs/<n-job_name>/``
 
 ``n`` is an integer used for ordering the build steps.
 
-Job directories **MUST** contain a script named ``job.sh`` which **MAY** 
+Job directories **MUST** contain a script named ``job.sh`` which **MAY**
 execute other scripts.
 
 Config files may optionally be created, and MUST be named ``config.ini`` and
@@ -78,11 +79,12 @@ Available config options:
   WARN_ON_FAILURE = True|False
   CONTAINER_BUILD = True|False
   CONTAINER_NAME = <string>
+  CONTAINER_ARCH = <string>
 
 
 Unless *all* jobs specify a "CONTAINER_NAME" in their custom config a
-container file **MUST** be present at ``<repo_root>/ci/Containerfile``.
-The container file will be built and used to run all of a repo's jobs 
+container file **MUST** be present at ``<repo_root>/contrib/ci/Containerfile``.
+The container file will be built and used to run all of a repo's jobs
 by default.
 
 All projects SHOULD have a ``build`` step and a ``test`` step, at a minimum.
@@ -92,24 +94,31 @@ Running CI Locally
 
 Running the CI scripts locally can be useful for development and testing.
 
-*Be aware that custom configs for a given job may specify a alternate
-container.*
-
-
-Example of building the environment and running a job locally:
+Included in each CI directory is a script which simplifies running jobs
+in the same way the CI Worker does, in containers, using ``podman``.
 
 ::
 
-  # From root of repo directory, build the container:
-  docker build -t <local_name_for_container> -f ci/Containerfile .  # <- don't forget the "."
-
-  # Then to run one of the job scripts. For example:
-  docker run --rm --volume $PWD:/workdir --workdir /workdir <local_name_for_container> ci/jobs/1-build/job.sh
-
-  # or to get an interactive shell in the container, with the repo mounted at /workdir:
-  docker run -ti --rm --volume $PWD:/workdir --workdir /workdir <local_name_for_container> /bin/bash
-
-
+  # Usage:
+  ./contrib/ci/ci.sh <job-name>
+
+  # For example, if the CI jobs tree looks like this:
+  ./contrib/ci/jobs
+    ├── 0-codespell/
+    ├── 1-build/
+    ├── 2-test/
+    ├── 3-docs/
+    ├── 4-deb-package/
+    └── 5-deploy-package/
+
+  # Then you can run job '0-codespell' as follows:
+  ./contrib/ci/ci.sh 0-codespell
+
+  # If you are using podman and have "qemu-user-binfmt" installed
+  # then you may attempt to run any job under an alternative CPU
+  # architecture by providing a second argument.
+  # For example:
+  ./contrib/ci/ci.sh 0-codespell arm64
 
 
 Additional Builders