Merge branch 'master' of https://git.fortiss.org/af3/maven-releng

Readme.md

@@ -24,3 +24,34 @@
   Contains the product descriptions by they are built, such as AF3.
 * releng
   Contains common configuration shared by all plugins, update site configs, and
+
+*Debugging Build Failures*
+
+Whenever a CI job fails, it may be caused by a problematic source code change, a
+bug in the maven-releng configuration, the docker image, or related to the
+gitlab CI pipeline. The following pieces of information shall provides hints to
+debug such issues.
+
+* As a first measure, ensure that the AF3 and Kernel builds in your local AF3
+  AF3 developer installation. Ensure that you are on the branches that you want
+  to test.
+* If this test succeeds, do a local AF3 maven build following the instructions
+  for a [local build](https://af3-developer.fortiss.org/projects/autofocus3/wiki/AF3_Build_Management#Local-Build).
+* If the build finishes sucessfully, check whether the failure is caused by the
+  docker container configuration. Therefore, on a linux machine, install the
+  gitlab-runner and docker packages and build the docker image locally by
+  executing `docker build -t maven-releng docker/` within your clone of this
+  repository.
+  Afterwards, execute the stage from the CI script that failed by executing
+  `gitlab-runner exec docker <job-name>`. Please not that pipelines are not
+  not supported if executing the gitlab-runner tool locally. Hence you must
+  ensure that all required build artifacts are available in the job to test.
+  For instance, if the test phase fails, the gitlab-ci.yml must be modified to
+  clone all submodules and use all build flags defined in the build job.
+  Finally, if the isse is resolved by a change in the Dockerfile, follow the
+  instructions in the *Structure* section to upload the changes to the gitlab
+  repository. Otherwise, just push the changes of the gitlab-ci.yml script.
+* If this point is reached, the CI build failure may caused by some pipeline
+  misconfiguration, for instance due to wrong artifact passing. Another likely
+  reason is an outdated docker image in the repositorie's Container Registry.
+