Revision as of 03:26, 30 May 2017

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".

Configure the Tycho version

When writing this tuturial, the new tycho-version-plugins goal "update-eclipse-metadata" we need is not released yet, so we have to use a tycho snapshot release. We have to add the Tycho snapshot plugin repository in the "itp01" parent pom:

 <pluginRepositories>
   <pluginRepository>
     <id>tycho-snapshots</id>
     <url>https://repo.eclipse.org/content/repositories/tycho-snapshots/</url>
   </pluginRepository>
 </pluginRepositories>

And change the tycho-version property from 1.0.0 to 1.1.0-SNAPSHOT:

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

Once Tycho 1.1.0 gets released, that additional pluginRepository is not needed anymore.

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 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</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 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 -DignoreSnapshots=true

NOTE: -DignoreSnapshots=true is only needed till Tycho version 1.1.0-SNAPSHOT get's released. This parameter tells the maven-release-plugin to allow snapshot dependencies within your project and it could be obmitted onces Tycho 1.1.0-SNAPSHOT gets released.

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.

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-SNAPSHOT</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>
 
   <pluginRepositories>
       <pluginRepository>
           <id>tycho-snapshots</id>
           <url>https://repo.eclipse.org/content/repositories/tycho-snapshots/</url>
       </pluginRepository>
   </pluginRepositories>
 
   <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</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 changes.
• The changes in the pom (done by the release plugin) and in the MANIFEST/feature/product files (done by the tycho plugin) are committed in 2 commits.