This package serves serval purposes:
1. Provide a script interface for CI
2. Provide RPM macros to create a CI test package from
   a source package.

The package should be split into a generic and HPC
specific part. This will happen when there is interest
in having this CI available for more projects than
just HPC.

1. The package introduces an additional directory structure:

  a. /usr/share/openqa/CI: Top directory for script libraries.
     aa. /usr/share/openqa/CI/libs: Directory to hold scripts 
     to be shared by multiple test packages.
  b. /var/lib/openqa/CI: Directory struture for test scripts, logs 
     and summaries
     ba. /var/lib/openqa/CI/log: holds log files that may be collected.
     bb. /var/lib/openqa/CI/results: directory containing the result summary
     bc. /var/lib/openqa/CI/citest: home directory for the test user 'citest'
     bd. /var/lib/openqa/CI/root: directory for tests to be executed under root

2. Interface to the CI:
   a. /usr/lib/openqa/CI/execute-tests.sh: script to be called as root.
      This script is also available under the standard search path as
      ci-openqa-tests.

   b. Return values:
      0: All tests succeeded.
      1: Test script failure
      2: root tests failed, testsuite aborted
      3: user tests failed, testsuite aborted
      4: some tests failed test suite continued
   c. There will be a test result ssummary in /var/lib/openqa/CI/results/summary.results
   d. Test scripts may copy logfiles to /var/lib/openqa/CI/log for root scripts
      and /var/lib/openqa/citest/ for user scripts.

3. Test scripts:
   a. Test scripts may log to stdout and stderr. All output will be saved.
   b. Test scripts should return 0 if successful and any value if failed.
      values > 127 will cause the tests to terminate innediately, values < 128
      will let it continue with the next test.
      The return value should not be 1 for user scripts as this indicates an
      failure of sudo.
   c. The tests may gather logs files in /var/lib/openqa/CI/log for root scripts
      and /var/lib/openqa/citest/ for user scripts.
   d. There may be multiple test scripts. Root and user scripts are run intermixed
      in lexical order. The may start with 01-, 02-, .. to run them in a specific
      order. If a root and a user script exists with the same name, the root script
      is run first.
       
4. Creating compliant tests:
   Tests are part of the source package. They need to be placed into a separate
   package.
   a. Add to the preamble of the spec file:
      %package  openqa-tests
      Summary:        OpenQA CI Test Package for %{name}
      Group:          Development/Tools/Other
      BuildRequires:  openqa-ci-tools-devel
      Requires:       openqa-ci-tools
      Requires:       %{name} = %{version}

      %description    openqa-tests
      Test package to verify installation and functionality of the %name package.
   b. during %install, to install test scripts, add
      %openqa_ci_root_install %{<sourcefile>}
      for a root script and
      %openqa_ci_user_install %{<sourcefile>}
      These macros will create the target directory if it doesn't exist.
   c. Add a files section:
      %files openqa-tests
      %defattr(-,root,root)
      %openqa_ci_root_test <root_script>.sh 
      %openqa_ci_user_test ci_user_test <user_script>.sh
   d. Each script inherits the environment variables:
       LIBS - contains script helpers to source
       LOG - Directory for collecting logs (ie log files written by an
       	     application run by the test suite)
       HOME - citest users home directory. Place scripts which should
       	      be run by a regular user in here.
       ROOTDIR - Home of root user for CI.
      This will make sure, the directories are set up correctly when
      using the installation macros.

   Use of convenience macros:
   1. Add 
      BuildRequires:  openqa-ci-tools-devel
      to base package. This is ugly but the macro to create the test package
      is defined exactly in this package.
   2. Add after %description section:
      %openqa_ci_package [-r <other_dependencies>][-n <package-to-test>][-a <exclusive_archs]
      use -r for other dependencies, -n if the name of the package to test
      is different from %{name}.
      If the main package has the ExclusiveArch: tag set, you need to specify exactly the
      same list with the -a option. If you need more than one architecture, separate them
      by commas, not spaces.
   3. Add to %install section:
      %openqa_ci_user_install %{S:<N_user>}
      %openqa_ci_root_install %{S:<N_root>}
      for any user/root script to add. <N_user>/<N_root> is the source tag
      number of the respective script.
   4. Add at end of the %files section list:
      %openqa_ci_files [-u %{S:<N_user>}|-r %{S:<N_root>}] [-n <base-package-name>]
      for user/root scripts to add. If more than one script is needed, separate them
      by commas (no spaces!). <N_user>/<N_root> is the source 
      tag number of the respective script. Add -n <package-to-test> if the name 
      of the package to test is different from %{name}.
   For more documentation check macros.openqa-ci.
