Usage

Prepare For Release

Before you can build releases with the unleash-maven-plugin some things must be prepared:

1. Add the plugin to your project or any of its parents. It is sufficient to add the plugin to the plugin-management section of your project since we will later execute the goal manually rather than embedding it into the build lifecycle.
2. Add the SCM connection URL to your project. This connection tells the plugin from where the project has been checked out and where to commit to or create tags. Note that the connection URL must be prefixed with scm:[scm-provider]: which indicates the provider implementation to choose. The URL can be declared as the connection or developerConnection. If both are declared the developerConnection URL takes precedence over the connection URL.
3. Add the required SCM provider implementation as a dependency to the unleash-maven-plugin. This is required to put the SCM provider implementation for the SCM type indicated by the prefix of the connection URL onto the classpath to ensure the unleash plugin can find and load the required provider.

<project>
  ...
  <scm>
    <connection>scm:git:git://github.com/user/project.git</connection>
    <developerConnection>scm:git:https://github.com/user/project.git</developerConnection>
    <tag>HEAD</tag>
  </scm>
  ...
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>com.itemis.maven.plugins</groupId>
          <artifactId>unleash-maven-plugin</artifactId>
          <version>1.0.0</version>
          <dependencies>
            <dependency>
              <groupId>com.itemis.maven.plugins</groupId>
              <artifactId>unleash-scm-provider-git</artifactId>
              <version>1.0.0</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Build The Release

In order to build the release at least one of the modules of the project must have a SNAPSHOT version assigned. This is also verified at the beginning of the release workflow. The simplest way to build the release is the invocation of the following command:

mvn unleash:perform

which is the shorter form of the following command:

mvn com.itemis.maven.plugins:unleash-maven-plugin:1.0.0:perform

This performs the default release workflow on the project which calculates the release and development versions, updates the POMs, builds the project, tags the SCM and installs and deploys the artifacts.

Custom SCM credentials

Sometimes it is necessary to provide SCM credentials to the SCM provider. This can be the case if the system does not cache the credentials or if you want to make SCM changes as a specific user. You can use the parameters scmUsername adn scmPassword for this purpose. When calling the goal from command line and providing these parameters through system properties the call would look like this:

mvn unleash:perform -Dunleash.scmUsername=... -Dunleash.scmPassword=...

Changing The Workflow

One of the core features of this plugin is to provide maximum flexibility by letting the user decide what the plugin/goal does and when it is done. This can be achieved by overriding the default workflow of the goal with a custom one. For that you only have to store your custom workflow in a file and provide the filepath to the plugingoal:

mvn unleash:perform -Dworkflow=[path_to_your_workflow_file]

Before overriding the workflow it would be useful to know about the default workflow and processing steps that are available for use. More info on that is available here: Maven CDI Utils

But in short, printing the default workflow of the goal can be requested by calling mvn unleash:perform -DprintWorkflow while printing a table with all processing steps available on classpath can be requested by calling mvn unleash:perform -DprintSteps

Adding Custom Processing Steps

Changing the default workflow by reorganizing the available processing steps or leaving out some of them is just one way to adapt the goal to your needs. Another one is to add further functionality that is shipped as different libraries or implemented by yourself. You can achieve this by adding the appropriate library to the plugin classpath (plugin dependency) and include steps provided by this library in your workflow. The library CDI Plugin Hooks provides some common processing step implementations, f.i. to execute shell commands, invoke maven goals or fire HTTP requests. This one is also used in the example below:

<project>
  ...
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>com.itemis.maven.plugins</groupId>
          <artifactId>unleash-maven-plugin</artifactId>
          <version>1.0.0</version>
          <dependencies>
            <!-- scm-provider dependency -->
            <dependency>
              <groupId>com.itemis.maven.plugins</groupId>
              <artifactId>cdi-plugin-hooks</artifactId>
              <version>0.1.1</version>
            </dependency>
          </dependencies>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

Adapted workflow with two exec steps, one at the beginning and one at the end. The workflow is stored in workflows/customPerform directly in the project:

exec[1]
storeScmRevision
checkProjectVersions
checkParentVersions
checkDependencies
checkPlugins
checkPluginDependencies
prepareVersions
checkAether
setReleaseVersions
addSpyPlugin
buildReleaseArtifacts
removeSpyPlugin
checkForScmChanges
tagScm
detectReleaseArtifacts
setDevVersion
installArtifacts
deployArtifacts
exec[2]

Calling the plugin with data for the exec steps. The first echos START and the second echos FINISH:

mvn unleash:perform -Dworkflow=workflows/customPerform -Dexec[1]="echo START" -Dexec[2]="echo FINISH"