Release procedure

Releases are performed using Maven 3.2.2 and onwards so you need to have that installed (see the building page). This page describes how the release process is handled.

Prerequisites

In order to release, you will need:

• An access to the Sonatype Nexus instance as a manager for the Codehaus Cargo project. Read more about it on the Initial Setup section of the OSSRH guide
• The GNU privacy guard (GPG) installed on your machine and at least one secret key.
  • The secret key's public part must have been uploaded to the MIT PGP Public Key Server.

• To provide your Sonatype Nexus credentials using your settings.xml file (in the ${user.home}/.m2/ directory). Here's an example settings.xml:

  <settings>
    [...]
    <servers>
      <server>
        <id>ossrh</id>
        <username>USERNAME</username>
        <password>PASSWORD</password>
      </server>
    </servers>
    [...]
  </settings>
  

Before you start

Before releasing, make sure what is going to be released is fully functional; in particular check that all containers pass all tests.

• All containers with a public download link are automatically tested by the Continous Integration system every time there is a code change:
  1. Open the CI page and click on the latest build
  2. First, check if the overall status is PASSED
  3. Then, click on the build and check for the command with cat core/samples/java/containers.log in it (on all threads). It should indicate status 0 for all containers:
     
     
     
     
• For non-publicly-downloadable containers, tests need to be done on your computer. These include:
  • JBoss 7.2.x, i.e. JBoss refers to as JBoss Enterprise Application Platform (EAP) version 6.1, and onwards
  • Glassfish 2.x
  • JRun 4.x
  • All versions of Orion/OC4J
  • All versions of WebLogic
  • All versions of WebSphere

Tagging and deploying on to the staging area

Start by erasing your local Maven repository (${user.home}/.m2/repository/, unless you've reconfigured this in your settings.xml). This will ensure that you don't have any artifacts cached locally that can't be found in public repositories.

The typical Maven release procedure is to execute these commands:

1. A dry-run before doing the actual release to ensure there aren't any problems:
   mvn clean release:prepare -DdryRun=true
2. mvn release:prepare: the actual release preparation, with the actual tagging process
3. mvn release:perform: deploys the tagged artifacts on the Sonatype Nexus staging repository
   • If you get a message saying: Error deploying artifact: Failed to transfer file. Return code is: 401 Unauthorized, please make sure your credentials in the settings.xml file are correct.

Promoting the staged version

Once the new Codehaus Cargo version is in the Sonatype Nexus staging repository, follow the below steps for promoting the staged version:

1. Follow the Releasing the Deployment guide in order to close the staging repository
2. Send an e-mail to the Codehaus Cargo list so users can try out the new version. We typically leave the vote open for 72 hours.
3. Once the developers/users also validate the version as being stable, follow the Releasing the Deployment guide in order to release the staging repository
   Note: If the version was not stable, that same guide also explains how to drop it
4. Log onto Codehaus Cargo JIRA, release the current version and add the next version.
5. Check that the Codehaus Cargo wiki is up to date. Specifically, perform the following updates:
   
   1. Modify the status on the home page about the delivery:
      
      • Make sure the Containers list is complete
      • Make sure the Navigation page is complete
      • Make sure the Javadocs for the Core Containers are complete
      • Make sure the documentation for each container is up to date.
        Note: The source files (that you need to import using the Insert -> Wiki markup option in each container's page manually) are generated in core/documentation/target/[container's name].log
      • Make sure the Containers with DataSource and Resource support is up to date.
        Note: The source file (that you need to import using the Insert -> Wiki markup option manually) is generated in core/documentation/target/datasource.log
      • Make sure the Project Structure is up to date.
        Note: The source file (that you need to import using the Insert -> Wiki markup option manually) is generated in core/documentation/target/project-structure.log
   2. Modify the Home page to update the available version number, the release notes URL the checkbox is pointing to and the release date
   3. Modify the Maven2 Plugin Installation page to update the SNAPSHOT version
   4. Create a blog post
   5. Export the wiki to a zipped HTML file (select all pages except for the Downloads (including all subsections) page) and add it the Downloads page
   6. Move the old version to the Archived Downloads page
      
      • Remember to move the old documentation archive from the Downloads page to that page as well
   7. Modify the Downloads page to update the download links, available version number, documentation and release note links
6. Check that the Codehaus Cargo Web site is up to date. Specifically, perform the following updates:
   1. Go to the generator subdirectory of the codehaus-cargo.github.io repository and run a mvn verify command to generate the Web site
   2. Download the source code of the tagged version in a temporary location and run a mvn javadoc:aggregate command to generate the API documentation
   3. Move the target/site/apidocs folder to the root of the codehaus-cargo.github.io repository
   4. Check in and push all changes, this will automatically update the Codehaus Cargo Web site
7. Send an announcement email to Cargo mailing lists ... and to other relevant sites you know about. Mailing lists of some servers can also be interesting.