Preparing to Release

• Make sure the site documentation is up to date and follows the Development Guidelines.
• All open JIRA issues should be closed or agreed to be scheduled for a future version.
• Plugin must be documented and preferably have unit and integration tests.
• If changes-report of maven-changes-plugin is used, update changes.xml to include all issues in JIRA that were fixed. (If jira-report is used, this information is retrieved automatically from JIRA.)
• If the release is a bugfix release (incrementing z): explicitly document the bugs fixed.
• If the release is a minor release (incrementing y): document the new features added. Make sure that these new features are properly documented, including:
  • Javadoc tags if the Mojo is written in Java
  • Examples
• Verify that the project doesn't depend on SNAPSHOTs anymore (the maven-release-plugin will check this too)
• Ensure the plugin complies with its intended minimum JRE requirement. For instance, if Java 1.5 is to be supported, actually set your JAVA_HOME to a JDK 1.5 and run mvn clean verify. This will catch references to classes or methods that were accidentally used but are only available in later versions of Java. Also consider to add our animal-sniffer-maven-plugin which can check the code against the signature of the required JDK version.
• To generate the documentation of the plugin, you will need to use at least Maven 2.1.0 because of the maven-site-plugin preconfigured in the mojo-parent. To deploy you can't use Maven 2.1.0 or 2.2.0, because they produce incorrect GPG signatures and checksums respectively. This means it requires at least Maven 2.2.1 to perform a complete release. But this doesn't mean you can't use an earlier version of Maven to build or use this plugin.
• Check that the POM properly declares its dependencies, i.e. run mvn dependency:analyze and fix any problems.
• To be able to use the maven-release-plugin you need to have a svn client available on your system path. To verify if it's there, execute svn help on the project root.
• Be sure you have generated a gpg-key before performing the release.

Graduating from the Sandbox

If the plugin is making its first official release, it should graduate from the sandbox. When this occurs, the following steps should be followed:

• Make sure the site follows the Development Guidelines.
• Call a vote for the graduation on the dev mailing list. See below for more info on how to do this. You can use a template for this call for promotion.
• Move the svn project from sandbox/ to mojo/.
• Ensure that you update any corresponding Continuous Integration plans to reflect the above svn location.
• Change the POM parent from mojo-sandbox-parent to mojo-parent noting the parent's most recent version from the mojo-parent svn tags folder.
• Move the plugin site link on the plugin list from the section "Sandbox Plugins" to "Pre-release Plugins" by editing the plugins.apt document. Redeploy the site and verify that it is functional.

Preparing for the First Production Release

When a plugin is ready to have its first production release (i.e. not an alpha or beta release) there are a couple of extra things that needs to be taken care of:

• Create a separate JIRA project for the plugin. Every production plugin must have its own JIRA project. Pre-production plugins share the MOJO project in JIRA. If you don't know how to do this, or don't have the necessary karma, just ask for help on the dev mailing list.
• Make sure that the plugin's site passes the documentation checker plugin test. Run

  mvn docck:check

  If there are any errors - fix them. There are a couple of errors that might not need to be fixed. As an example: it's better not to add an FAQ document than to add a bogus one.

Making GPG Keys

Before releasing for the first time you have to generate a GPG key and publish it. Information can also be found on Sonatype's How To Generate PGP Signatures With Maven.

• Download GPG from http://www.gnupg.org/download/ , follow the instructions and install it to your system. Verify your gpg installation by running gpg with the version flag, i.e. gpg --version
• Execute gpg --gen-key and answer the questions. Most of the time you can use the default.

  Please select what kind of key you want: (1) DSA and Elgamal (default) (2) DSA (sign only) (5) RSA (sign only)	1
  What keysize do you want? (2048)	2048
  Please specify how long the key should be valid. 0 = key does not expire n = key expires in n days nw = key expires in n weeks nm = key expires in n months ny = key expires in n years Key is valid for? (0)	0
  Key does not expire at all Is this correct? (y/N)	y
  Real name:	your real name
  Email address:	your email address
  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit?	O

• Execute gpg --list-sigs "your real name" && gpg --armor --export "your real name" and visit http://pgp.mit.edu/ to distribute your public key, so users can verify your files. This webpage contains a form where you have to copy your key.
• Update https://svn.codehaus.org/mojo/site/src/site/resources/KEYS by expanding this file with your key. If you deploy the site by running mvn site:deploy the key will become available on the mojo-site. Since all mojo-developers should put their key here it's easy for users to verify mojo-artifacts.

Importing CA Certificates

One part of a release is deploying the site documentation. Before being able to do so you have to import the Codehaus CA certificates into your JDK keystore. Follow the Codehaus instructions for Installing a new CA into the JDK.

Preparing your environment

For any deployment you have to make contact with one of the Codehaus servers, for which authentication is required. The best way to do this is to include the following sections in your personal settings.xml and fill in the xircles.username and xircles.password properties with your own credentials.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <server>
      <id>codehaus.org</id> <!-- used for site deployment -->
      <username>jqhacker</username> <!-- xircles.username -->
      <password>SeCrEt</password> <!-- xircles.password -->
    </server>           
    <server>
      <id>codehaus-nexus-staging</id> <!-- used for release deployment -->
      <username>jqhacker</username> <!-- xircles.username -->
      <password>SeCrEt</password> <!-- xircles.password -->
    </server>           
    <server>
      <id>codehaus-nexus-snapshots</id> <!-- used for snapshot deployment -->
      <username>jqhacker</username> <!-- xircles.username -->
      <password>SeCrEt</password> <!-- xircles.password -->
    </server>
  </servers>
  <profiles>
    <profile>
      <id>verify-stage</id> <!-- convenience profile -->
      <repositories>
        <repository>
          <id>codehaus-nexus-staging</id>
          <url>https://nexus.codehaus.org/content/groups/staging/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>codehaus-nexus-staging</id>
          <url>https://nexus.codehaus.org/content/groups/staging/</url>
          <releases>
            <enabled>true</enabled>
          </releases>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
</settings>          

(Note that using Maven password encryption is possible but may not work in combination with the xircles.password property, perhaps due to difficulties with brace expansion. Instead, duplicate your encrypted password into each of the server sections.)

Staging the Release

The release process should be done using the Maven Release Plugin:

• Execute mvn release:prepare

  This will make sure all code is checked in, tag the release and make sure the POM has no snapshot dependencies. If your local username is not the same as your codehaus username, be sure to add -Dusername=<codehaus username>.

• Execute mvn release:perform

  This will build the plugin, javadocs and source. Everything will be deployed to the Nexus Repository Manager, ready to be staged. Be aware, that the site will be built and deployed as well. This means the site will up to date before the voting has even started. Trying to update the site afterwards seems to be much more complicated, this way we can assure the site will reflect the intended version.

• Verify that the plugin site deployment occurred successfully.
• Log into https://nexus.codehaus.org/ and "Close" the staging repository.

Call a Vote

Before a release can occur, a vote typically takes place. This is initiated with an email to the dev list, preferrably with a subject that starts with [vote]. Explain the plugin, status and any other info you feel relevant. The standard is to wait 72 hours for responses. This gives other developers time to verify the quality of the plugin before placing their vote. See the Apache Voting Guidelines for more information. You can use a template to be sure your email contains all the expected information.

Promoting the Release

When the vote has passed, do the following:

• Reply to the latest vote and summarize the result and prefix the subject with [RESULT].
• Log into https://nexus.codehaus.org/ and "Release" the staging repository.
• Wait some time and find the artifacts synced on central. The synchronization typically occurs every 4 hours but allow for it take up to 24 hrs.
• Update the plugins.apt document to reflect the new release. Redeploy the mojo site by executing mvn site-deploy and verify that it is functional.
• Record the release date for the version in the plugin's JIRA project and create a new version for future development/issues.
• Send out an annoucement email to announce@mojo.codehaus.org, dev@mojo.codehaus.org, user@mojo.codehaus.org and users@maven.apache.org. You can use a template to be sure your email contains all the expected information.
• TODO: if there's a feed containing all releases, get the release into that feed.

Dropping the Release

If the vote failed, the following steps have to be taken:

• Log into https://nexus.codehaus.org/ and "Drop" the staging repository.
• Rollback any SCM-changes. Be aware that the release:rollback doesn't remove the tag. You must do this by hand.

Releasing the Mojo Parent POM

Of course, to release the Mojo Parent POM, a vote takes place just for an ordinary plugin release. But when it comes to actually perform the release, there are some differences to watch out for:

1. Execute mvn release:prepare
2. Execute mvn release:perform -Dgoals=deploy

   The important thing to note here is the parameter -Dgoals=deploy. By default, the Release Plugin would execute the phases deploy and site-deploy on the parent POM. However, the site of the parent POM is not meant to be deployed, we have a separate project for this. The configuration of the site distribution in the parent POM exists solely for the purpose of inheritance by the plugins. Accidentally deploying the parent's site would damage the Mojo website, most notably the index.html.

3. Test that the new parent is working

   Manually update (without committing) one or two plugins on your local machine to use the new parent. Then run:

   mvn clean verify site -Pmojo-release

4. Update the Development Guidelines to indicate the new POM version.