Apache Commons logo

Release Plugin

This is a Maven 3.x Plugin which is used by Apache Commons releases. See the Development page for information to help maintain this plugin.

The main purpose of the plugin is to automate the steps of our, namely The Apache Commons Project's, release process. Currently we have the mechanics for detaching distribution artifacts (i.e. all tar.gz artifacts and signatures as well as all .zip artifacts and signatures), creating a site.zip file, and staging all of those artifacts in a subversion repository (for the most part a subdirectory of https://dist.apache.org/repos/dist/dev/commons/. It can, however, stage to any subversion repository.

Plugin Goals

Available Goals (which are meant to be used together; the only reason they are separated is for code readability):

  • commons-release:detach-distributions - Remove tar.gz, tar.gz.asc, zip, and zip.asc files from being uploaded to nexus and copy them to the target/commons-release-plugin directory.
  • commons-release:stage-distributions - Take all staged files in the target/commons-release-plugin directory, and the RELEASE-NOTES.txt from the root of the project, and commit them to a specified staging subversion repository.
  • commons-release:vote-txt -Dcommons.nexus.repo.id=nnnn [-Dgit.tag.name] # where nnn is the number following orgapachecommons- in the Nexus 'Repository' column

Using the plugin

Configure the plugin as the last plugin in the<build> section of the pom.xml

N.B. This is now done in the Commons Parent POM, so is not needed in the component POM.

<plugin>
  <groupId>org.apache.commons</groupId>
  <artifactId>commons-release-plugin</artifactId>
  <version>1.8.0</version>
  <executions>
    <execution>
      <id>clean-staging</id>
      <phase>post-clean</phase>
      <goals>
        <goal>clean-staging</goal>
      </goals>
    </execution>
    <execution>
      <id>detach-distributions</id>
      <phase>verify</phase>
      <goals>
        <goal>detach-distributions</goal>
      </goals>
    </execution>
    <execution>
      <id>stage-distributions</id>
      <phase>deploy</phase>
      <goals>
        <goal>stage-distributions</goal>
      </goals>
    </execution>
  </executions>
</plugin>

The following properties need to be defined in the component POM if not already defined

    <properties>
          <!-- Previous version of the component (used for reporting binary compatibility check)-->
          <commons.bc.version>m.n</commons.bc.version>
          <commons.release.isDistModule>true</commons.release.isDistModule>
    </properties>

Ensure your Release Manager details are defined in your Maven ~/.m2/settings.xml file (These are used by the vote-txt goal) Properties have to be defined in a profile. For example:

<settings>
  ...
  <profiles>
    ...
    <profile>
      <id>active-profile</id>
      <properties>
        <commons.releaseManagerName>Your Name</commons.releaseManagerName>
        <commons.releaseManagerKey>Your Signing Key Hex ID</commons.releaseManagerKey>
      </properties>
    </profile>
  </profiles>

  <activeProfiles>
    <!-- define active profile name -->
    <activeProfile>active-profile</activeProfile>
  </activeProfiles>
  ...
</settings>

After the above configuration performing the release would occur by (note. more in depth details can be found at Preparations For A Release):

  1. creating our release branch,
  2. checking compatibility,
  3. checking your dependencies,
  4. checking javadocs and code style,
  5. checking the apache license,
  6. configure the build to generate a complete set of release artifacts,
  7. preparing the release notes, updating the download file and other autogenerated files,
  8. tagging the release candidate, and
  9. running the following command:
    mvn -Duser.name=<yourApacheId> [-Duser.password=<yourApacheIdsPassword] [-Dcommons.release.dryRun=true -Ptest-deploy] -Prelease clean test site deploy
    
To avoid specifying distribution credentials at the command line, consider using the distServer plugin configuration parameter (property commons.distServer) to specify a server definition in Maven settings.xml which defines your (encrypted, right?) authentication info.

If the component is new, then, before running this maven command, you would want to create the requisite subversion directory https://dist.apache.org/repos/dist/dev/commons/foo. Notice, that the way to perform a dry run of the release you need to include -Dcommons.release.dryRun=true -Ptest-deploy.