Deploying IzPack Versions to Public Repositories

General Requirements

• You need to import the Sonatype OSS CA certificate to your local JDK.
• You must be an IzPack developer at Github.
• You need a GnuPG public key.
  
  

Create and Export a GnuPG Key

Your public key must be added to the KEYS file in the source code parent directory:

gpg --list-sigs "your real name" >> KEYS
gpg --armor --export "your real name" >> KEYS

Export your public key to a public key server:

gpg --keyserver search.keyserver.net --send-key <your_key_id>

Without your GPG key exported to a public key server you won't be able to close a Sonatype Nexus staging repository and thus activating new releases. 

In case of trouble exporting from the command line you could try submitting your key via the web UI of a keyserver of your choice, for example: http://pool.sks-keyservers.net:1137

For more information on how to create and distribute GPG keys, look at the GNU Privacy Handbook.

Configure Sonatype Nexus credentials

Sonatype Nexus requires authentication usign the following convention in your $M2_HOME/settings.xml:

<servers>
 
    <!-- Sonatype Nexus -->
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>your.username</username>
      <password>{encrypted_password}</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>your.username</username>
      <password>{encrypted_password}</password>
    </server>

</servers>

You must have an JIRA account at Sonatype and use the appropriate credentials here for getting permission to upload files.

For information on how to encrypt your personal password see the Maven documentation.

Install the Sonatype OSS CA Certificate into the Java JDK

For deployments you need to add the oss.sonatype.org certificate to the list of accepted certificates of your JDK.

1. Open the link https://oss.sonatype.org/service/local/staging/deploy/maven2 in your browser (for instance Firefox)
2. Click on the security icon in the URL bar and open and save the certificate (for instance as oss.sonatype.org.pem)
3. Install the downloaded certificate into the JDK
   
   

#!/bin/bash
export JAVA_HOME=/usr/java/jdk1.8.xx
KEYSTORE=$HOME/.keystore
pushd $(dirname $0)
$JAVA_HOME/bin/keytool -importcert -alias Sonatype-OSS-CA -file ~/Downloads/IzPack-Migration/Sonatype/oss.sonatype.org -trustcacerts -keystore $KEYSTORE
popd

In case of using your own keystore, you must tell Maven to use it by exporting special Maven options:

export MAVEN_OPTS="-Djavax.net.ssl.keyStore=$HOME/.keystore \
    -Djavax.net.ssl.keyStorePassword=<your_keystore_pwd> \
    -Djavax.net.ssl.trustStore=$HOME/.keystore \
    -Djavax.net.ssl.trustStorePassword=<your_truststore_pwd"

Deploying IzPack Snapshots

Any IzPack developer is encouraged to publish new -SNAPSHOT versions as they publish changes to the Codehaus Git repository. Public snapshot deployments can be done each time by a developer provided the code passes automatic tests (do not skip tests before deploying).

Test your snapshot locally by deploying it to the local repository:

mvn clean install

Deploying a snapshot to the wild is done by:

mvn clean verify deploy

Deploying IzPack Releases

For your own security, using --batch-mode is not really recommended since you have to enter your GPG passphrase in clear text on the command line, which could be saved for example in .bash_history. Rather wait and enter this passphrase as soon as Maven requests it on the command line input.

You need to activate the release profile to generate sources, javadoc and gpg signatures. This can be alternatively achieved by adding -DperformRelease=true to the Maven command line call.

As an example, we will consider the release of version 5.2.2.

Do a dry run

mvn -DperformRelease=true -Dtag=izpack-5.2.2 release:prepare -DdryRun=true -DreleaseVersion=5.2.2 -DdevelopmentVersion=5.2.3-SNAPSHOT

Release!

Build locally and prepare the staging repository at Sonatype Nexus:

Please note that some child modules are excluded from the build per profile buildDLL. The Maven Release Plugin will not update their project versions in the POM. Therefore it is necessary to explicitly run the versions-maven-plugin to fix them.

export JAVA_HOME=/usr/java/jdk1.8.xx
RELEASE_VERSION=5.2.2
DEVELOPMENT_VERSION=5.2.3-SNAPSHOT
# Preparing the release
mvn release:clean
mvn -Dtag=izpack-${RELEASE_VERSION} -DreleaseVersion=${RELEASE_VERSION} -DdevelopmentVersion=${DEVELOPMENT_VERSION} release:prepare
# Fixing the versions of the native child modules not deployed by default
mvn -N org.codehaus.mojo:versions-maven-plugin:2.2:update-child-modules -DnewVersion=${DEVELOPMENT_VERSION}
git add -u
git commit --amend --no-edit
git push
mvn org.codehaus.mojo:versions-maven-plugin:2.2:commit
# Perform the release
# Check your HTTP proxy settings in settings.xml and whether the proxy is reachable (required for deployments to the staging repo)
mvn -DperformRelease=true release:perform
rm izpack-native-parent/*/pom.xml.versionsBackup

It is not necessary to push the local POM changes and tags to Github after releasing any longer, thus commands like:

git push origin master
git push --tags origin master

won't have any effect, the remote repository will be already up to date at this stage

Close, promote and release from the staging repository at Sonatype Nexus:

Follow the instructions described in Releasing the Deployment.

The following sequence is just necessary if the nexus-staging-maven-plugin is configured to not automatically push the staged release to the Releases repository (which isn't currently the case):

Log in to OSSRH available at https://oss.sonatype.org/, check the staging repository and if everything is fine, Close and Release it (in this order).

Notes:

• You may not be able to perform release:prepare without having the HTTP credentials set in settings.xml, to be able to upload files to the staging storage at Sonatype OSS Nexus

• You may not be able to close a Nexus staging repository without having your GPG key exported to a key server.

• Things work better if your local account name matches the one at Sonatype, and you don't have to specify the username parameter. Otherwise, things may break, especially the Git pushes.

Recovering from Failed Releases

Recover the GIT repository

To undo a failed release, clean up untracked files by issuing:

mvn clean release:clean

Say our project was at version 5.2.2-SNAPSHOT. Preparing a release will remove the -SNAPSHOT suffix, commit and tag the code on Github, then update the project version to 5.2.3-SNAPSHOT.

If you need to undo the release, revert the changes with

git reset --hard HEAD~2

and delete the tag with

git tag --delete izpack-5.2.2

followed by

git push origin :refs/tags/izpack-5.2.2

The remote repository is resynchronized by:

git push --force

Recover the staging repository

Log in to OSSRH available at https://oss.sonatype.org/, select the the staging repository entry which failed and drop it.

Post-processing and Announcing Releases

Use the following channels for announcements:

1. Website izpack.org: https://github.com/izpack/izpack.github.com, automatically deployed to http://izpack.org
2. Blog news.izpack.org: Register and post an announcement. The new post should be directly shared from Blogger to
   1. Google+
   2. Twitter
3. Mailing list: izpack-announce@google-groups.com