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 provide 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.xml. Furthermore, each release should be briefly summarised in index.xml

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.

The IIPC repository should be checked out, and committed and pushed, including any documentation changes. The repository should be checked out using SSH. 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

This asks for the release version and the new version, does a 'dry run' of the release process, tags the repository, and pushes the tag (I think!). 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.

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.