Skip to content

Releasing

Jump to bottom
Jonathan Austin edited this page Jul 15, 2019 · 9 revisions

This page is intended for bordertech developers with authority to deploy com.github.bordertech releases to Maven Central. The rest of this document assumes deployment to Maven Central and primarily uses WComponents as an example project.

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 to com.github.bordertech. 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.

Create Release Activity Branch

Running the mvn release commands below makes changes in Git including your remote repository. Therefore, make sure you create a new activity branch before running these commands. This also helps for rolling back unsuccessful builds and deploys.

More information on workflow is available here.

mvn commands

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 -Darguments="-DskipTests -Dbt.qa.skip=true -Ddependency-check.skip=true"

For smaller projects you may wish to omit -Darguments

Tests can be skipped because they are run prior to any pull request being merged. The release process clones WComponents from GitHub to ensure that the clean code is being released, ensuring the tests have been run.

Releasing to Central

The mvn release commands will have created a staging repository in sonatype. This needs to be released into the central repository.

Steps to Release the Deployment:-

  • Login into https://oss.sonatype.org/
  • Locate and Examine the comgithubbordertech-* repository under Staging Repository
  • Select the repository and click Close action
  • Select the repository and click Release action

Refer to http://central.sonatype.org/pages/releasing-the-deployment.html for more detail.

Pull Request

The [building] step will have committed the updated pom.xml files into your release activity branch. Create a pull request from this branch and merge.

Release Notes

Once you have successfully completed the release you should head over to WComponents tags and publish release notes on the TAG created by the Building step. Look at older releases for examples of what is expected (hint, the changelog entry for your release is essentially pasted into your release notes).

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.

Using WComponents as an example:

  1. Delete your branch and sync so your origin is clean.
  2. If the branch made it as far as upstream (so only deployment failed) also delete the branch fromGitHub.
  3. Remove all pom.xml.releaseBackup files (one per module).
  4. Remove release.properties (in wcomponents-parent).
  5. Delete the tag wcomponents-parent-[RELEASE_NUMBER] For example to delete a failed build 0.0.1 the commands would be
  • git tag --delete wcomponents-parent-0.0.1
  • git push --delete origin wcomponents-parent-0.0.1
  1. Delete the deployment tag from GitHub.

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 (Java 7 and earlier);
  • network failure (including proxy problems).

TODO

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

Clone this wiki locally