[test] Documentation for packaging tests

qa/vagrant/pom.xml

@@ -35,6 +35,9 @@
       <!-- rpmbuild location : default to /usr/bin/rpmbuild -->
       <packaging.rpm.rpmbuild>/usr/bin/rpmbuild</packaging.rpm.rpmbuild>
 
+      <!-- This version is consistently available in maven central so its useful
+           for now but it doesn't have any guarantee of compatibility so it
+           should be switched out with 2.0.0 once that is released. -->
       <upgrade.from.version>2.0.0-beta1</upgrade.from.version>
     </properties>
 

qa/vagrant/src/test/resources/packaging/scripts/packaging_test_utils.bash

@@ -232,7 +232,9 @@ verify_package_installation() {
     fi
 }
 
-# Install the rpm or deb package
+# Install the rpm or deb package.
+# -u upgrade rather than install. This only matters for rpm.
+# -v the version to upgrade to. Defaults to the version under test.
 install_package() {
     local version=$(cat version)
     local rpmCommand='-i'
@@ -332,6 +334,8 @@ clean_before_test() {
     done
 }
 
+# Start elasticsearch and wait for it to come up with a status.
+# $1 - expected status - defaults to green
 start_elasticsearch_service() {
     local desiredStatus=${1:-green}
 
@@ -404,7 +408,8 @@ stop_elasticsearch_service() {
     fi
 }
 
-# Waits for Elasticsearch to reach a given status (defaults to "green")
+# Waits for Elasticsearch to reach some status.
+# $1 - expected status - defaults to green
 wait_for_elasticsearch_status() {
     local desiredStatus=${1:-green}