File README.updating of Package openstack-monasca-persister-java-kit

This package provides build dependencies for building monasca-persister using
using Tetra (ruby2.2-rubygem-tetra). Using Tetra is neccessary due
monasca-persister'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-persister-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-persister-java-kit.tar.xz for a new
version of monasca-persister, 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-persister-java{,-kit} working copy.

1) Download an updated monasca-persister stable tarball. We'll use the version
   number resulting from extracting this tarball for the package. At the time
   of this writing this was 1.12.1.dev4 for the stable/rocky tarball.

2) Update monasca-common-java-kit and monasca-common-java if required. This
   step may not be needed. Unfortunately there is no hard and fast rule for
   determining whether this is needed. Just attempt the package's build with
   the current monasca-common version and update it if it fails.

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

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

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

5) Perform a dry-run build with Tetra:

     cd /tmp/openstack-monasca-persister-java/src/monasca-persister-1.12.1.dev4
     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-persister-java/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.
     VERSION=$(basename $(find ../../kit/m2/monasca-common/monasca-common/* -maxdepth 1 -type d))
     export POM_FILE=$(readlink -e ../../kit/m2/monasca-common/monasca-common/${VERSION}/monasca-common-${VERSION}.pom)

     # Actual openstack-monasca-persister-java build
     mvn clean 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-persister-java/packages/openstack-monasca-persister-java-kit/openstack-monasca-persister-java-kit.tar.xz

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

Note: these instructions applied for openstack-monasca-persister-1.12.1.dev4 and
may not be sufficient for more recent monasca-persister versions. If they turn
out to yield a broken kit tarball and you end up fixing it, please update this
file. Thank you!