# Codehaus Cargo : Release procedure

Created by Former user, last modified by S. Ali Tokmen on Jun 08, 2025

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 `ArtifactTransferException`s 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 Maven Central as a manager for the Codehaus Cargo project.
- 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 Maven Central token for the org.codehaus.cargo namespace provided using your `settings.xml` file (in the `${user.home}/.m2/` directory). Here's an example `settings.xml`:

      <settings>
        [...]
        <servers>
          <server>
            <id>central</id>
            <username>YOUR_TOKEN_USERNAME</username>
            <password>YOUR_TOKEN_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, deploying and publishing to Maven Central

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.

Once the deployment has uploaded and validated successfully, log in to the Maven Central: Publishing page to publish it.

### Promoting the released version

Once the new Codehaus Cargo version is in the Maven Central, follow the below steps for promoting that new version:

1. Log onto Codehaus Cargo JIRA, release the current version and add the next version.
2. 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 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
3. 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
4. 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.

How to insert using the Wiki Markup

To insert content using Wiki Markup:

1. Edit the document in the Codehaus Confluence
2. Clear the existing content by selecting all content and pressing delete on your keyboard
3. On the toolbar, click Insert -> Wiki markup:
4. Paste the wiki markup content

## Attachments:

Insert wiki markup.png (image/png)