File README.updating of Package openstack-monasca-thresh-kit

This package provides build dependencies for building monasca-thresh using
using Tetra (ruby2.2-rubygem-tetra). Using Tetra is neccessary due
monasca-thresh's Maven based build process downloading dependencies at build
time. Tetra will keep track of these downloaded dependencies during a so-called
"dry-run" build on the maintainer's machine and generate a tarball
(openstack-monasca-thresh-kit.tar.xz) containing all of them. This tarball
is then used to allow the same build to run in an offline manner in OBS (where
there is no Internet connectivity on purpose in order to allow for reproducible
builds). To generate openstack-monasca-thresh-kit.tar.xz for a new
version of monasca-thresh, proceed as follows (you will need to have Tetra
installed for this):

Note: these steps need to be performed on the machine where you keep your
openstack-monasca-thresh{,-kit} working copy.

1) Download an updated monasca-thresh tarball. We'll assume the new
   tarball's version is stable-rocky throughout the rest of this file, which is the
   version it was at at the time of this writing. Please substitute  by the
   actual tarball version number wherever it occurs.

2) You may have noticed that we referred to a "tarball version" rather than
   just a "version" in the previous step. This is because the monasca-thresh
   tarball contains a Python and a Java implementation. The Python
   implementation supplies the tarball's version number which does _not_ match
   the Java implementation version number. You will find the Java version
   number in the <version> tag in pom.xml. Look up this version number for your
   tarball now at the time of this writing it was 2.1.1 which we will use for
   the remainder of the text. Please substitute it by your own tarball's Java
   implementation version number wherever it occurs.

3) Update monasca-common-java-kit and monasca-common-java if required. This
   step may not be needed. Check mon.common.version property in the 
   monasca-thresh tarball's java/pom.xml to see if an update is neccessary.

   If the version specified in that property is already packaged (check the
   <version> tag of the pom.xml file contained in the java-monasca-common 
   source tarball - and yes, this is screwed up) you will not need to update
   monasca-common-kit and monasca-common.

4) Install the java-monasca-common package of the appropriate version to
   your development machine.

5) Initialize a tetra build directory for your new monasca-thresh tarball 
   by running these commands from your openstack-monasca-thresh working copy:

     # OBS checkouts may have colons in their directory names which messes with some
     # Java build tools, so use a neutral location:
     cp rocky.tar.gz maven-repo-from-environment.patch /tmp
     cd /tmp
     tetra init openstack-monasca-thresh rocky.tar.gz
     # Needed to accomodate Tetra's custom location for the local maven
     # repository (openstack-monasca-thresh is hardwired for ~/.m2)
     patch -d /tmp/openstack-monasca-thresh/src/monasca-thresh-stable-rocky/ -p1 < /tmp/maven-repo-from-environment.patch

6) Perform a dry-run build with Tetra:

     cd /tmp/openstack-monasca-thresh/src/monasca-thresh-stable-rocky/
     tetra patch   # otherwise Tetra will complain about changes from maven-repo-from-environment.patch
     tetra dry-run
     mvn clean

     # Install monasca-common jars and get their dependencies into the Maven cache.
     cp -a /usr/share/java/monasca-common ../../kit/m2
     mvn dependency:resolve

     # Make sure run_maven.sh finds a mvn executable to run in PATH. Otherwise it
     # will quietly fail to run, causing us to miss tons of dependencies.
     export PATH=$PATH:/tmp/openstack-monasca-thresh/kit/apache-maven-3.3.9/bin/

     # We need this because otherwise common/build_common.sh will
     # think monasca-common is not in the cache.
     export POM_FILE=$(readlink -e ../../kit/m2/monasca-common/monasca-common/1.3.0-SNAPSHOT/monasca-common-1.3.0-SNAPSHOT.pom)

     # Actual openstack-monasca-thresh build
     mvn package
     mvn dependency:go-offline

     # remove java-monasca-common jars (we'll get these from the
     # java-monasca-common BuildRequire during the real build).
     rm -rf ../../kit/m2/monasca-common/

     exit

7) Generate the new kit tarball:

     tetra generate-all

You will now find an updated kit tarball in
/tmp/openstack-monasca-thresh/packages/openstack-monasca-thresh-kit/openstack-monasca-thresh-kit.tar.xz

Substitute this tarball for the existing one in the kit package and bump its
version.

Note: these instructions applied for monasca-thresh's stable/rocky branch and
may not be sufficient for more recent monasca-thresh versions. If they turn out
to yield a broken kit tarball and you end up fixing it, please update this
file. Thank you!