Readme.md

**Maven build configuration for local and jenkins builds**

***Structure***

* bundles
  Holds the sources to compile the product. Each repository added here as a git
  submodule (see .gitmodules) must contain a generic pom.xml file to enable
  pomless builds. Please see https://git.fortiss.org/af3/af3.git for an example
  of such a pom file.
* docker
  Contains the build specification for the docker container used in the CI Jobs.
  Build & Update instructions:
  * Clone the repository.
  * Navigate to the cloned directory in a UNIX shell and apply the following
    commands.
  * `docker login git.fortiss.org:5001 -u <USERNAME>`
  * `docker build -t git.fortiss.org:5001/af3/maven-releng docker/`
  * Delete the outdated 'af3/maven-releng' container
  * `docker push -t git.fortiss.org:5001/af3/maven-releng`
* features
  Holds the feature descriptions that compose a product. Each source bundle must
  be listed here.
* products
  Contains the product descriptions by they are built, such as AF3.
* releng
  Contains common configuration shared by all plugins, update site configs, and

***Updating references***

To update references to AF3 in order to build a new release 
 * execute `git submodule update --remote` in root maven-releng and
 * commit and push changes

***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.