Fork me on GitHub

Performing a Release

This is a check list of stuff that has to be done before a new version of a plugin is released.

Preparing to Release

  • Make sure the site documentation is up to date and follows the Development Guidelines.
  • All open GitHub 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 GitHub that were fixed. (If github-report is used, this information is retrieved automatically from GitHub.)
  • 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
  • Make sure you include the correct information in the scm section:
    <project>
      <scm>
        <connection>scm:git:https://github.com/mojohaus/PLUGIN_NAME.git</connection>
        <developerConnection>scm:git:ssh://git@github.com/mojohaus/PLUGIN_NAME.git</developerConnection>
        <url>https://github.com/mojohaus/PLUGIN_NAME</url>
      </scm>
    </project>
    
    • 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 git client available on your system path. To verify if it's there, execute git 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.
  • 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://github.com/mojohaus/mojohaus.github.io/blob/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.

Preparing your environment

For any deployment you have to make contact with oss.sonatype.org, 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 oss-sonatype.username and oss-sonatype.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>ossrh-staging</id> <!-- used for release deployment -->
      <username>jqhacker</username> <!-- oss-sonatype.username -->
      <password>SeCrEt</password> <!-- oss-sonatype.password -->
    </server>           
    <server>
      <id>ossrh-snapshots</id> <!-- used for snapshot deployment -->
      <username>jqhacker</username> <!-- oss-sonatype.username -->
      <password>SeCrEt</password> <!-- oss-sonatype.password -->
    </server>
  </servers>
</settings>          

(Note that using Maven password encryption is possible but may not work in combination with the oss-sonatype.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. Make sure that you are able to push changes and tags via SSH

  • Execute mvn release:perform

    This will build the plugin, javadocs and source. Everything will be deployed to the Nexus Repository Manager of Sonatype OSSRH, ready to be staged. (This will typically not build the site.)

  • Log into https://oss.sonatype.org/ and "Close" the staging repository.
  • Build and deploy the plugin site

    Typically, the command is cd target/checkout mvn verify site site:stage scm-publish:publish-scm but could vary. Consult the mojo's README file.

  • Verify that the plugin site deployment occurred successfully.

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://oss.sonatype.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.
  • Record the release date for the version in the plugin's GitHub project and create a new version for future development/issues.
  • Send out an annoucement email to mojohaus-dev@googlegroups.com and users@maven.apache.org. You can use a template to be sure your email contains all the expected information. Ensure you've subscribed to all these mailing lists, otherwise the message will be bounced.
  • 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://oss.sonatype.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, use git tag -d myplugin-1.2.3.
  • To remove a remote tag on GitHub, use git push origin :refs/tags/myplugin-1.2.3
  • Run siteskinner:skin -DsiteDeploy to restore the documention of the latest released plugin.

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.