Using WSO2 Release Helper Plug-In

The WSO2 Release Helper plug-in was introduced to help the Apache Maven Release plug-in to prepare releases of WSO2 specific Maven projects (ESB and Registry). These projects contain artifact.xml files consisting of meta-data (including versions) of the project artifacts, which need to be updated with both release version (tag) and the next development version (trunk) during the release preparation. The WSO2 Release Helper plug-in addresses this requirement. 

The Apache Maven Release plug-in provides two entry points (shown below) for other plug-ins in the release:prepare goal.

• preparationGoals - Goals to run as part of the preparation step, after transformation from snapshot versions to release version, but before committing.

• completionGoals - Goals to run on completion of the preparation step, after transformation back to the next development version, but before committing.

Two goals have been introduced in the WSO2 Release Helper plug-in that should be executed as a preparation goal and a completion goal of the Apache Maven Release plug-in:

• prepare-release: Finds any ESB and Registry projects in the local repository and updates the artifact.xml files with the release version for each particular project. Finally, commits the updated artifact.xml files.
• prepare-snapshot: Finds the ESB and Registry projects in the local repository and updates the artifact.xml files with the next dev version for each particular project. Finally, commits the updated artifact.xml files.
   

A sample configuration for the Maven Release plug-in with the WSO2 Release Helper plug-in is shown below:

<plugin>
    <artifactId>maven-release-plugin</artifactId>
    <version>2.5</version>
    <configuration>
	 <preparationGoals>               
          org.wso2.maven:wso2-release-helper-plugin:1.0.0-SNAPSHOT:prepare-release
       </preparationGoals>
       <completionGoals>
          org.wso2.maven:wso2-release-helper-plugin:1.0.0-SNAPSHOT:prepare-snapshots
       </completionGoals>
    </configuration>
</plugin>

For more information, see Using Maven Release Plug-In.

Rolling back a release preparation

The WSO2 Release Helper plug-in supports rolling back a release preparation. However, the rollback goal of the WSO2 Release Helper plug-in must be invoked prior to invoking the rollback goal of the Maven Release plug-in.

This is because the WSO2 Release Helper plug-in depends heavily on additionally generated files (release.properties and backup pom.xml files) that are created during the release:prepare goal of the Maven Release plug-in. The WSO2 Release Helper plug-in uses these files to capture release versions, snapshot versions, backup versions and SCM properties. Since the release:rollback goal of the Maven Release plug-in will wipe out these files, the above constraint should be met in order for the rollback goal of the WSO2 Release Helper plug-in to function properly.

To execute a rollback, execute the following goal in the root of the SCM repository.

org.wso2.maven:wso2-release-helper-plugin:1.0.0-SNAPSHOT:rollback

commit message: [wso2-release-plugin] rollback the release of ${ReleaseTag}

Similar to the rollback goal of the Maven Release plug-in, the SCM tag will not get modified (or removed) by the rollback and it will have to be manually removed from the SCM repository.

Running in dryRun mode

The WSO2 Release Helper plug-in supports the dryRun mode of the Maven Release plug-in. It will automatically detect when the Maven Release plug-in is running in dryRun mode. Similar to the Maven Release plug-in, two additional artifact.xml files named artifact.xml.tag and artifact.xml.next are generated for each WSO2 project with changes done for the release version and the next development version. Any changes will not be committed in the dryRun mode.

WSO2 Release Helper plug-in detects the dryRun mode of the Maven Release plug-in by scanning .tag and .next files generated by the Maven Release plug-in. Therefore, after running in dryRun mode, these files should be cleared prior to executing release:prepare again with dryRun switched off.

Externalizing SCM credentials

The WSO2 Release Helper plug-in supports externalized SCM credentials to prevent them from being added in the pom.xml files. Credentials can be passed as console args or can be configured in the settings.xml file of the Maven installation.

Passing as console args

To pass as console args to the Maven Release plug-in, use the following command: mvn release:prepare -Dusername=user -Dpassword=pass

Configuring credentials in the settings.xml file

The WSO2 Release Helper plug-in uses the Maven SCM plug-in for SCM related tasks. While both the Maven SCM and the Maven Release plug-ins support externalizing SCM credentials, there is a small difference in the configurations. Therefore, the following configurations are needed in order to support both the WSO2 Release Helper and Maven Release plug-ins.

1. Add the following entry to the settings.xml file of the Maven conf folder in order to support the WSO2 Release Helper plug-in (and Maven SCM plug-in):

   <server>
     <id>hostname</id>
     <username>username</username>
     <password>password</password>
   </server>

   See here for more information.
   
   Note that the ID of the server must be the host name of the SCM connection URL. For example, if the SCM URL is https://github.com/wso2/developer-studio.git, then the ID should be github.com.

   
   

2. To support the Maven Release plug-in, add the server entry as mentioned in step 1. Then add the following property in the parent pom.xml file:

   <properties>
      <project.scm.id>hostname<project.scm.id>
   </properties>

   See here for more information.

   Even though the Maven Release plug-in supports any name as the server ID, in order to support both the WSO2 Release Helper and Maven Release plug-ins, this property also should be equivalent to the host name of the SCM URL.