Releasing

This page is intended for WComponents framework developers with authority to deploy WComponents releases. The rest of this document assumes deployment to Maven Central.

Configuring the build machine - One time setup

On the build machine you need to install GPG and create a key pair so the build can cryptographically sign the built artefacts. Read this.

The configuration of the signing plugin does not go in the main pom file since it contains secrets and machine specific configuration. Instead you should create a profile in the settings.xml file (example below).

You also need an OSS Sonatype account with authority to deploy WComponents. The account credentials will need to be provided in the settings.xml file (example below).

Your settings.xml file should look a little something like this:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
	<profiles>
		<profile>
			<id>sonatype-oss-release</id>
			<properties>
				<gpg.keyname>539ED197</gpg.keyname>
				<gpg.passphrase>*********</gpg.passphrase>
				<!-- All below items are optional extra configuration for older GPG installs. -->
				<gpg.defaultKeyring>false</gpg.defaultKeyring>
				<!-- <gpg.executable>/usr/local/bin/gpg</gpg.executable> -->
				<gpg.useagent>true</gpg.useagent>
				<gpg.lockMode>never</gpg.lockMode>
				<gpg.homedir>/home/banana/.gnupg</gpg.homedir>
				<gpg.publicKeyring>/home/banana/.gnupg/pubring.gpg</gpg.publicKeyring>
				<gpg.secretKeyring>/home/banana/.gnupg/secring.gpg</gpg.secretKeyring>
			</properties>
		</profile>
	</profiles>
	<servers>
		<server>
			<!-- The id here must match the id of the repositories in the pom file's distributionManagement -->
			<id>ossrh</id>
			<username>mrbanana</username>
			<password>********</password>
		</server>
	</servers>
</settings>

The build currently uses maven-release-plugin to save a lot of the manual "pom shuffle" work. It needs to connect to SCM so using GitHub as an example you would need to configure access by following these steps:

1. Generate new SSH key
2. Add public SSH key to GitHub

OS X

To build the release on OS X you will need the Xcode command line tools.

Building

Please ensure you are building using the correct versions of Java and Maven. For example: Java 1.7.0_79 and Maven 3.2.2.

Warning - running the commands below makes changes in Git including your remote repository. Make sure you create a new activity branch before running these commands.

Three release goals are needed and you should ensure you activate the correct profile in your settings.xml. For example if your profile is sonatype-oss-release.

mvn release:clean release:prepare release:perform -Psonatype-oss-release

Memory

Running a complete deploy with all tests (since the Selenium tests were reinstated) may result in a permgen outOfMemory error on some systems. There are a few ways to avoid this in the unlikely event it occurs:

1. increase the permSize e.g. on UNIX-like system export MAVEN_OPTS='-XX:MaxPermSize=256m' (256m is not required, it is an example - 128m should be plenty) then run the deployment build;
2. skip 'optional' Selenium tests by adding -DskipOptionalTests=true to the command line above (not recommended);
3. skip all tests by adding -DskipTests to the command line above (really not recommended).

You should only resort to the second or third options above if you are very short of memory and have done a full build of wcomponents-parent with all tests prior to running the deploy.

Releasing

http://central.sonatype.org/pages/releasing-the-deployment.html

TODO

Maybe this would be useful: http://central.sonatype.org/pages/manual-staging-bundle-creation-and-deployment.html

Dealing with failure

If your release build fails (for a reason other than you did not test it first and your code is broken) the best thing to do is delete your feature branch (you did create a new feature branch for this build didn't you?), do some manual clean-up and start again.

Clean up steps

You may not have to do all of these: it depends how far through the process the failure occurred.

1. Delete your branch and sync so your origin is clean.
2. Remove all pom.xml.releaseBackup files (one per module).
3. Remove release.properties (in wcomponents-parent).
4. Delete the tag wcomponents-parent-[RELEASE_NUMBER] For example to delete a failed build 0.0.1 the commands would be
   • git tag -d wcomponents-parent-0.0.1
   • git push origin :refs/tags/wcomponents-parent-0.0.1
   • git push remote :refs/tags/wcomponents-parent-0.0.1 (just in case it got this far)
5. Delete the deployment tag from GitHub (in the Code > Releases > Tags view).

This should get you back to where you started. You probably want to re-sync everything then create a new feature branch ready to start again.

Some common gotchas

The following have caused failures in the past:

• not setting up GPG correctly;
• not setting up the release profile correctly (see above);
• forgetting to use the release profile;
• running out of permgen space;
• network failure;
• proxy issues.