Release procedure

This page describes how the release process is handled.

Prerequisites

In order to release, you will need:

• JDK 11. Please note that older or newer versions of the JDK cannot build all of Codehaus Cargo, and hence should not be used to release new versions.
• Maven 3.6.3 or newer, though it is for sure a good idea to use the latest Maven version available.
  With Maven 3.8.1 onwards, you might have some ArtifactTransferExceptions with the OW2 snapshot repository (which was defined as HTTP over a decade back). You can work around these using the instructions in the chapter ArtifactTransferException with Maven 3.8.1 onwards.
• 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.

• Your Sonatype Nexus credentials provided 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 Continous Integration system
  2. Click on the latest build
  3. Check if the overall status is PASSED. In case the overall status is FAILED, look in the workflow to see which build(s) or container(s) cause the failure, and fix.
• For non-publicly-downloadable containers, tests need to be done on your computer. These include:
  • JBoss 7.2.x, i.e. what JBoss refers to as the 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 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
        As an alternative to manual processing, you can also set the Java property cargo.confluenceCredentialsPath to let the build update the Confluence content for each and every container.
      • 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
        As an alternative to manual processing, you can also set the Java property cargo.confluenceCredentialsPath to let the build update the Confluence content for the Containers with DataSource and Resource support page.
      • 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 Building and Maven 3 Plugin Installation pages 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.