Release Procedure

Full details of how to perform releases are in the Sonatype guide - here we present a breakdown of the major steps, and add some additional details concerning documentation.

Most of the configuration mentioned in the SonaType guide is taken care of by the parent pom (org.sonatype.oss:oss-parent). Local configuration in addition to this is described under their relevant paragraphs.

Step 1: Credentials

Like SNAPSHOT releases, publication of releases requires SonaType credentials with access to the org.netpreserve namespace. In the case of Build management, this can be done with static authorisation keys held in the config.

However, full releases must be performed manually, and so we must ensure that various users have the rights to do this. We can add comments on the original ticket for that namespace in order to request the appropriate permissions.

In order to sign the build artefacts, the individual performing the release must also create an appropriate PGP signature. Again, Sonatype provides detailed information on how to set this up.

Step 2: Documentation

For each project, the documentation should be up to date. In particular, the log of changes to the code should record each of the issues and pull-requests that have been resolved since the last release.

For webarchive-commons this is in the CHANGES.md file.

For OpenWayback, the full details are in release_notes.md. Furthermore, each release should be briefly summarised in index.md.

Step 3: Maven Release Process

Following the appropriate Sonatype guidelines, we can now perform the actual release. As mentioned above, you need to have your credentials set up (including your Sonatype username/password in your ~/.m2/settings.xml), and you also need the full JDK available so the build process can run javadoc.

This is an example of an settings.xml file:

    <settings>
      ...
      <servers>
        <server>
          <id>github</id>
          <username>github-username</username>
          <password>github-password</password>
        </server>
        <server>
          <id>sonatype-nexus-snapshots</id>
          <username>sonatype-username</username>
          <password>sonatype-password</password>
        </server>
        <server>
          <id>sonatype-nexus-staging</id>
          <username>sonatype-username</username>
          <password>sonatype-password</password>
        </server>
      </servers>
      ...
    </settings>

The entry for the GitHub account is needed to deploy the Site. The SonaType credentials are needed for deployment.

As of Oktober 2014 there is a bug in the GitHub site module (version 0.10) which require that you set username and public email address in your GitHub profile. See this issue https://github.com/github/maven-plugins/issues/69

Due to new restrictions on size of data submitted with the GitHub site module, we are no longer deploying the site with the Maven release plugin. Instead this is done as a separate step as documented at the bottom of this page.

The IIPC repository should be checked out using SSH in a clean directory.

$ git clone git@github.com:iipc/openwayback.git

You need to generate SSH-keys and add it to your GitHub account. This is needed because Maven uses SSH to tag the release on GitHub.

Now you are ready to do the actual release. You run this:

$ mvn release:prepare -DpushChanges=false

This asks for the release version and the new version (as well as the GPG Passphrase for your PGP signature mentioned above), does a 'dry run' of the release process, updates the pom.xml files with the new version (x.x.x-SNAPSHOT), and tags the repository. -DpushChanges=false prevents automatically pushing the tag and pom.xml changes to GitHub. Then, you do this:

$ mvn release:perform 

This checks out the tagged version and runs the release process on it. This means building, running tests, generating the javadoc, tagging the build artefacts, and uploading the artefacts to the Sonatype release server. For OpenWayback, the build process also uploads the Maven site documentation to GitHub Pages, just as for a SNAPSHOT build.

If things are good, you can push the pom.xml changes and tag generated in the mvn release:prepare step to GitHub with:

$ git push origin HEAD:master
$ git push origin --tags

When the build goes wrong

Occasionally, the build process can go a bit wrong. You can use:

$ mvn release:rollback

to change the Maven POM back to the original version. However, note that you will have to delete the tagged version from git before you can attempt to re-release that version, and that the tag will also need to be deleted from the remote (origin). Google 'git delete remote tag' for details.

Step 4: Close and Release to Maven Central

There are two more final steps to carry out, via the Sonatype system. Go to https://oss.sonatype.org/, login, and go to staging repositories. Your release package should be on that list (usually at the bottom, so you can change the Repository sort order to see it at the top).

You can look inside and check it looks ok. If so, select it, and select 'Close'. This closes the release, and so prevents any additional artefacts being added to the same package. This also performs some validation checks, which can take a little while.

Eventually, after a refresh, the package will be marked as closed. You can then select it and click 'Release'. This will release the binary package and, after a couple of hours, you package will show up in Maven Central.

Step 5: Update Maven generated site documentation

Check out the newly created release and build the site documentation

$ git checkout -b <VERSION> openwayback-<VERSION>
$ mvn clean
$ mvn site

Check out branch gh-pages and copy the generated site into it.

$ git checkout gh-pages
$ cp -r target/staging <VERSION>

Update 'latest' symlink

$ rm latest
$ ln -s <VERSION> latest

Commit and push the new site

$ git add <VERSION>
$ git commit -m 'Creating site for <VERSION>'
$ git push

The last thing that needs to be done is to create a link in the Releases section. This is done by pushing the tag.

$ git push origin tags/openwayback-<VERSION>

The site pages should show up in http://iipc.github.io/openwayback/<VERSION>

Step 6: GitHub Release

If you want to turn the GitHub tag into a release, you can edit the tagged version (perhaps add the release notes and add assets as at https://github.com/iipc/openwayback/releases/tag/openwayback-2.4.0) in the GitHub interface.

Contributor Keys

Name	Organization	Address	Code Signing Key Fingerprint	Key Id
Nick Ruest	York University	ruebot at keybase dot io	159493E15691C84D615B7D1B417FAF1A0E1080CD	0E1080CD
Lauren Ko	Univ. of North Texas	lauren dot ko at unt dot edu	511E7364E21CE9C9790550369DAA450076190F5D