Procedure 18.2. Release Procedure

The script dev-support/make_rc.sh automates many of these steps. It does not do the modification of the CHANGES.txt for the release, the close of the staging repository in Apache Maven (human intervention is needed here), the checking of the produced artifacts to ensure they are 'good' -- e.g. extracting the produced tarballs, verifying that they look right, then starting HBase and checking that everything is running correctly, then the signing and pushing of the tarballs to people.apache.org. The script handles everything else, and comes in handy.

1. Update the CHANGES.txt file and the POM files.

   Update CHANGES.txt with the changes since the last release. Make sure the URL to the JIRA points to the proper location which lists fixes for this release. Adjust the version in all the POM files appropriately. If you are making a release candidate, you must remove the -SNAPSHOT label from all versions. If you are running this receipe to publish a snapshot, you must keep the -SNAPSHOT suffix on the hbase version. The Versions Maven Plugin can be of use here. To set a version in all the many poms of the hbase multi-module project, use a command like the following:

   $ mvn clean org.codehaus.mojo:versions-maven-plugin:1.3.1:set -DnewVersion=0.96.0
                       

   Checkin the CHANGES.txt and any version changes.

2. Update the documentation.

   Update the documentation under src/main/docbkx. This usually involves copying the latest from trunk and making version-particular adjustments to suit this release candidate version.

3. Build the source tarball.

   Now, build the source tarball. This tarball is Hadoop-version-independent. It is just the pure source code and documentation without a particular hadoop taint, etc. Add the -Prelease profile when building. It checks files for licenses and will fail the build if unlicensed files are present.

   $ mvn clean install -DskipTests assembly:single -Dassembly.file=hbase-assembly/src/main/assembly/src.xml -Prelease
                           

   Extract the tarball and make sure it looks good. A good test for the src tarball being 'complete' is to see if you can build new tarballs from this source bundle. If the source tarball is good, save it off to a version directory, a directory somewhere where you are collecting all of the tarballs you will publish as part of the release candidate. For example if you were building a hbase-0.96.0 release candidate, you might call the directory hbase-0.96.0RC0. Later you will publish this directory as our release candidate up on people.apache.org/~YOU/.

4. Build the binary tarball.

   Next, build the binary tarball. Add the -Prelease profile when building. It checks files for licenses and will fail the build if unlicensed files are present. Do it in two steps.

   1. First install into the local repository

      $ mvn clean install -DskipTests -Prelease

   2. Next, generate documentation and assemble the tarball.

      $ mvn install -DskipTests site assembly:single -Prelease

   Otherwise, the build complains that hbase modules are not in the maven repository when you try to do it at once, especially on fresh repository. It seems that you need the install goal in both steps.

   Extract the generated tarball and check it out. Look at the documentation, see if it runs, etc. If good, copy the tarball to the above mentioned version directory.

5. Create a new tag.

   Point Release Only

   The following step that creates a new tag can be skipped since you've already created the point release tag

   Tag the release at this point since it looks good. If you find an issue later, you can delete the tag and start over. Release needs to be tagged for the next step.

6. Deploy to the Maven Repository.

   Next, deploy HBase to the Apache Maven repository, using the apache-release profile instead of the release profile when running the mvn deploy command. This profile invokes the Apache pom referenced by our pom files, and also signs your artifacts published to Maven, as long as the settings.xml is configured correctly, as described in Example 18.2, “Example ~/.m2/settings.xml File”.

   $ mvn deploy -DskipTests -Papache-release

   This command copies all artifacts up to a temporary staging Apache mvn repository in an 'open' state. More work needs to be done on these maven artifacts to make them generally available.

7. Make the Release Candidate available.

   The artifacts are in the maven repository in the staging area in the 'open' state. While in this 'open' state you can check out what you've published to make sure all is good. To do this, login at repository.apache.org using your Apache ID. Find your artifacts in the staging repository. Browse the content. Make sure all artifacts made it up and that the poms look generally good. If it checks out, 'close' the repo. This will make the artifacts publically available. You will receive an email with the URL to give out for the temporary staging repository for others to use trying out this new release candidate. Include it in the email that announces the release candidate. Folks will need to add this repo URL to their local poms or to their local settings.xml file to pull the published release candidate artifacts. If the published artifacts are incomplete or have problems, just delete the 'open' staged artifacts.

   hbase-downstreamer

   See the hbase-downstreamer test for a simple example of a project that is downstream of HBase an depends on it. Check it out and run its simple test to make sure maven artifacts are properly deployed to the maven repository. Be sure to edit the pom to point to the proper staging repository. Make sure you are pulling from the repository when tests run and that you are not getting from your local repository, by either passing the -U flag or deleting your local repo content and check maven is pulling from remote out of the staging repository.

   See Publishing Maven Artifacts for some pointers on this maven staging process.

   Note

   We no longer publish using the maven release plugin. Instead we do mvn deploy. It seems to give us a backdoor to maven release publishing. If there is no -SNAPSHOT on the version string, then we are 'deployed' to the apache maven repository staging directory from which we can publish URLs for candidates and later, if they pass, publish as release (if a -SNAPSHOT on the version string, deploy will put the artifacts up into apache snapshot repos).

   If the HBase version ends in -SNAPSHOT, the artifacts go elsewhere. They are put into the Apache snapshots repository directly and are immediately available. Making a SNAPSHOT release, this is what you want to happen.

8. If you used the make_rc.sh script instead of doing the above manually, do your sanity checks now.

   At this stage, you have two tarballs in your 'version directory' and a set of artifacts in a staging area of the maven repository, in the 'closed' state. These are publicly accessible in a temporary staging repository whose URL you should have gotten in an email. The above mentioned script, make_rc.sh does all of the above for you minus the check of the artifacts built, the closing of the staging repository up in maven, and the tagging of the release. If you run the script, do your checks at this stage verifying the src and bin tarballs and checking what is up in staging using hbase-downstreamer project. Tag before you start the build. You can always delete it if the build goes haywire.

9. Sign and upload your version directory to people.apache.org.

   If all checks out, next put the version directory up on people.apache.org. You will need to sign and fingerprint them before you push them up. In the version directory run the following commands:

   $ for i in *.tar.gz; do echo $i; gpg --print-mds $i > $i.mds ; done
   $ for i in *.tar.gz; do echo $i; gpg --armor --output $i.asc --detach-sig $i  ; done
   $ cd ..
   # Presuming our 'version directory' is named 0.96.0RC0, now copy it up to people.apache.org.
   $ rsync -av 0.96.0RC0 people.apache.org:public_html
                       

   Make sure the people.apache.org directory is showing and that the mvn repo URLs are good. Announce the release candidate on the mailing list and call a vote.