Tycho/Release Workflow

Doing a Tycho project release with the maven-release-plugin

This is a small tutorial that describes what configuration changes need to be done to use the maven-release-plugin (http://maven.apache.org/maven-release/maven-release-plugin/index.html) to release a Tycho project. If you are not familiar with the maven-release-plugin visit the plugin website to get an overview of how the release plugin works.

Prerequisite

The easiest way to get an example Tycho project is to use one of the tycho-demo repository. In this tutorial the itp01 Tycho project is used. In order to demonstrate the release process including comitting and pushing, you have to fork and clone the tycho-demo project from github:

1) Fork the https://github.com/eclipse/tycho-demo repository

2) Clone the forked repository:

 git clone https://github.com/<yourgithubuser>/tycho-demo.git

3) Open the parent pom.xml file of the project: <pathToLocalGitRepo>/itp01/pom.xml.

Configure the SCM

The maven release plugin does commit and push the changes done during the release process (pom version changes, tagging, etc), so you have to add the scm information to that pom:

 <scm>
   <connection>scm:git:https://github.com/<yourgithubuser>/tycho-demo.git</connection>
   <developerConnection>scm:git:https://github.com/<yourgithubuser/tycho-demo.git</developerConnection>
 </scm>

The credentials used by the maven scm plugin are taken from the settings.xml file, so add a server configuration to your ~/.m2/settings.xml file:

  <servers>  
     <server>
        <id>github.com</id>  
        <username>YOUR_GITHUB_USERNAME</username>  
        <password>YOUR_GITHUB_PASSWORD</password>  
     </server>   
  </servers>
  

Note that the <id> must match the hostname so it must be "github.com". Also note that YOUR_GITHUB_PASSWORD should be a Personal Access Token from > Settings > Developer settings > Personal access tokens. Usually the normal github password will not work.

Configure the Tycho version

To use Tycho in combination with maven-release-plugin, the goal "update-eclipse-metadata" is required, which is available since release 1.1.0. Therefore, the following property should be set and used for configuring Tycho plugin versions in your build:

 <tycho-version>1.1.0</tycho-version>

Target Platfrom Configuration

In case a target definition file is part of the build reactor the target definition project should have the same version as the ${project.version} maven variable, because then the target-platform-configuration could look like this:

 <plugin>
   <groupId>org.eclipse.tycho</groupId>
   <artifactId>target-platform-configuration</artifactId>
   <version>${tycho.version}</version>
   <configuration>
    <target> 
       <artifact>
           <groupId>com.vogella.tycho</groupId>
           <artifactId>com.vogella.tycho.target</artifactId>
           <version>${project.version}</version>
       </artifact>
   </target>

Without this the build will fail since the old version of the target definition cannot be found any more because the target definition project's version will also change during a release build.

Configure the maven-release-plugin

The maven-release-plugin does have a goal called "prepare" which does different things, including:

a) Changing the version in the poms from x-SNAPSHOT to a new version (you will be prompted for the version to use)

b) Commit (and push) the modified poms

c) Bump the version in the poms to a new value y-SNAPSHOT (these values will also be prompted for)

Step a) does update the versions only in the pom.xml files, so without any additional configuration the MANIFEST/feature/product files would still have the .qualifier versions in them and a build will fail because the pom and MANIFEST versions have to match. We have to use the new goal of the tycho-version-plugin to update the versions in the MANIFEST/feature/product files based on their respective pom versions. The maven-release-plugin does have a configuration parameter called "preparationGoals". All maven goals listed there are executed after the POM versions had been changed (and before committing). So this is the place where the tycho-versions-plugin must update the MANIFEST/feature/product files to their respective pom versions. Step b) does commit the modified POMs. Because the maven-release-plugin does only commit the pom files and not the changed MANIFEST/feature/product files, we have to call 2 additional goals to add and commit the changed eclipse files using the maven-scm-plugin (goals "add" and "checkin").

So the configuration of the maven-release-plugin does look like this:

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-release-plugin</artifactId>
   <version>2.5.3</version>
   <configuration>
     <preparationGoals>org.eclipse.tycho:tycho-versions-plugin:${tycho-version}:update-eclipse-metadata org.apache.maven.plugins:maven-scm-plugin:1.9.5:add org.apache.maven.plugins:maven-scm-plugin:1.9.5:checkin</preparationGoals>
   </configuration>
 </plugin>

Three additional goals are called after the POM versions had been changed: update-eclipse-metadata to update the MANIFEST/feature/product/update site files to the new version, add the changed files to the git changeset, checkin (=commit and push) the changed Eclipse/OSGi files. To make sure, that the maven-scm-plugin does only add, commit and push the MANIFEST/feature/product files, you could configure the maven-scm-plugin with a "default-cli" execution with an include pattern:

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-scm-plugin</artifactId>
   <executions>
     <execution>
       <id>default-cli</id>
       <goals>
         <goal>add</goal>
         <goal>checkin</goal>
       </goals>
       <configuration>
         <includes>**/META-INF/MANIFEST.MF,**/feature.xml,**/*.product,**/category.xml</includes>
         <excludes>**/target/**</excludes>
       <message>Changing the version to reflect the pom versions for the release</message>
       </configuration>
     </execution>
   </executions>
 </plugin>

Step c) is quite the same as step a). It changes the pom versions (to the new development version). So again the tycho-version-plugin must also change the MANIFEST/feature/product/update site files after that happened and that changed files must also be committed and pushed. For additional steps that needs to be done after the pom versions get bumped to the new development version, the maven-release-plugin's configuration parameter "completionGoals" could be used:

The maven-release-plugin configuration with the preparationGoals and completionGoals:

 <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-release-plugin</artifactId>
   <version>2.5.3</version>
   <configuration>
     <preparationGoals>org.eclipse.tycho:tycho-versions-plugin:${tycho-version}:update-eclipse-metadata org.apache.maven.plugins:maven-scm-plugin:1.9.5:add org.apache.maven.plugins:maven-scm-plugin:1.9.5:checkin</preparationGoals>
     <completionGoals>org.eclipse.tycho:tycho-versions-plugin:${tycho-version}:update-eclipse-metadata org.apache.maven.plugins:maven-scm-plugin:1.9.5:add org.apache.maven.plugins:maven-scm-plugin:1.9.5:checkin</completionGoals>
   </configuration>
 </plugin>

Commit the changed pom

You could not perform or prepare a release on a dirty worktree, so you have to commit the changes you have done in the pom file, e.g:

 git add pom.xml
 git commit -m "Adding release configurations"
 git push

Prepare the release

Now you should be ready to use the maven-release-plugin for this Tycho project and you could run:

 mvn release:prepare 

When calling mvn release:prepare you will be asked for the release version for each bundle, for the tag that should be used for this release and for the new development versions. There are parameters that could be used to set this things for your project, so that the preparation could be executed without user input. The release version and the following development version is specified as follows:

 mvn release:prepare -DreleaseVersion=1.0.0 -DdevelopmentVersion=1.0.1-SNAPSHOT

Performing a release

When the preparation was done successfully, you could call the perform goal in order to checkout the created release tag, build the project, run the tests and deploy the artifacts. In this tutorial we focus on the release preparation, not where and how to publish the release so configuring the distribution management is out of scope. To perform a release that just builds the release artifacts and installs them in your local maven repository, use the "goals" parameter of the maven-release-plugin's "perform" goal:

 mvn release:perform -Dgoals="clean install"

After the build succeeds, you do have a "target" folder in the project's root directory, containing the release artefacts and they got installed in your local maven repository.

Parent pom for the tycho-demo/itp01 project

This is the pom file containing all our changes:

   <?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
   <modelVersion>4.0.0</modelVersion>
   <groupId>tycho.demo.itp01</groupId>
   <artifactId>parent</artifactId>
   <version>1.0.0-SNAPSHOT</version>
   <packaging>pom</packaging>
 
   <modules>
       <module>tycho.demo.itp01</module>
       <module>tycho.demo.itp01.tests</module>
   </modules>
 
   <properties>
       <tycho-version>1.1.0</tycho-version>
   </properties>
 
   <scm>
       <connection>scm:git:https://github.com/mschreiber/tycho-demo.git</connection>
       <developerConnection>scm:git:https://github.com/mschreiber/tycho-demo.git</developerConnection>
       <tag>HEAD</tag>
   </scm>
 
   <repositories>
       <repository>
           <id>helios</id>
           <layout>p2</layout>
           <url>http://download.eclipse.org/releases/helios</url>
       </repository>
   </repositories>
   
   <build>
       <plugins>
           <plugin>
               <groupId>org.eclipse.tycho</groupId>
               <artifactId>tycho-maven-plugin</artifactId>
               <version>${tycho-version}</version>
               <extensions>true</extensions>
           </plugin>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-release-plugin</artifactId>
               <version>2.5.3</version>
               <configuration>
                   <preparationGoals>org.eclipse.tycho:tycho-versions-plugin:${tycho-version}:update-eclipse-metadata org.apache.maven.plugins:maven-scm-plugin:1.9.5:add org.apache.maven.plugins:maven-scm-plugin:1.9.5:checkin</preparationGoals>
                   <completionGoals>org.eclipse.tycho:tycho-versions-plugin:${tycho-version}:update-eclipse-metadata org.apache.maven.plugins:maven-scm-plugin:1.9.5:add org.apache.maven.plugins:maven-scm-plugin:1.9.5:checkin</completionGoals>
               </configuration>
           </plugin>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-scm-plugin</artifactId>
               <executions>
                   <execution>
                       <id>default-cli</id>
                       <goals>
                           <goal>add</goal>
                           <goal>checkin</goal>
                       </goals>
                       <configuration>
                           <includes>**/META-INF/MANIFEST.MF, **/feature.xml, **/*.product,**/category.xml</includes>
                           <excludes>**/target/**</excludes>
                           <message>Changing the Eclipse files versions</message>
                       </configuration>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
 </project>

Drawbacks

• Rollback does not rollback the MANIFEST/feature/product/update site changes.
• The changes in the pom (done by the release plugin) and in the MANIFEST/feature/product/update site files (done by the tycho plugin) are committed in 2 commits.

Unleash maven plugin

There is another maven plugin available which is worth looking at, the unleash-maven-plugin: https://github.com/shillner/unleash-maven-plugin