Make Agents Yourself

h1. MAY Plugin Release Process

{{>toc}}

MAY is an Eclipse plugin, it is thus distributed using an Eclipse update site, but parts of it are also available through Maven Central for [[MAY Maven Standalone Setup|standalone use without Eclipse]].

h2. General Overview

h3. Phases

Releasing MAY implies different phases:

# Preparing for the release

# Tagging the release on Mercurial

# Deploying the release on Maven Central

# Deploying the release in the update site

# Preparing the next development cycle

All of this is of course fairly automatised using Maven and Tycho for integrating the Eclipse aspects with Maven.

h3. Modules

MAY is decomposed in 5 different software modules (which are 5 Maven projects and some of them Eclipse artefacts):

* *fr.irit.smac.may.speadl.parent*: it contains general Maven instructions shared by the other modules.

* *fr.irit.smac.may.speadl*: it contains the code for the Eclipse plugin, without the UI aspects, and it is also the Maven artefact needed for [[MAY Maven Standalone Setup|standalone use without Eclipse]].

* *fr.irit.smac.may.speadl.ui*: it contains the UI code for the Eclipse plugin.

* *fr.irit.smac.may.speadl.feature*: it is an installable unit from the update site that combines the two previous Eclipse plugins.

* *fr.irit.smac.may.speadl.updatesite*: it contains everything needed for generating and deploying the update site containing the previous feature.

Only the first two are deployed to Maven Central.

The plugins and the features will end up in the update site.

h3. Syntactical Version Numbering

The Eclipse plugins follow the OSGI version numbering and it is stored in the *MANIFEST.MF* file of each project.

The Maven artefact follows the Maven version numbering and it is stored in the *pom.xml* file of each project.

All are using the 3 digits "SemVer":http://semver.org/ system (Major.Minor.Patch).

For the plugins, this is followed by a qualifier (Major.Minor.Patch.qualifier) that is replaced with the compilation time and date.

For the Maven artefacts, for non-release (development versions), this is followed  by the SNAPSHOT element (Major.Minor.Patch-SNAPSHOT) that is replaced with the compilation time and date.

So the plugins always have the qualifier while the Maven artefacts have the SNAPSHOT information only for development.

h3. Semantic Version Numbering

The MAJOR number changes when the syntax is incompatible with the previous one.

The MINOR number changes when the generated code is incompatible with the previous one.

The PATCH number changes for the rest.

h3. Example

For the sake of this guide, we will consider that we are releasing a new version numbered 3.4.0 (and thus we were developing 3.4.0-SNAPSHOT).

h2. Preparing for the Release and Tagging it

First, everything must be committed to Mercurial before doing the version update (this can be verified with @hg status@ before).

Let's say we just finished developing the 3.4.0-SNAPSHOT version and want to release the new 3.4.0 version.

h3. Updating the POM Files

We must update the POM files to reflect that, but do not touch the MANIFEST files:

<pre>

$ cd fr.irit.smac.may.speadl.parent

$ mvn -Dtycho.mode=maven versions:set -DnewVersion=3.4.0

</pre>

This is done from the parent directory and will impact all the modules.

The @-Dtycho.mode=maven@ argument tells Maven not to try to resolve Eclipse aspects that takes time and are useless here.

Now our Maven artefacts are versioned 3.4.0 while the plugins are versioned 3.4.0.qualifier.

h3. Tagging the Release

Now we commit these changes and tag them in Mercurial:

<pre>

$ hg commit -m "prepare for 3.4.0 release"

$ hg tag v3.4.0

</pre>

The commit must only change the POM files, nothing else (this can be verified with @hg status@ before).

h2. Deploying the Release on Maven Central

Then, the release has to be deployed to Maven Central:

<pre>

$ mvn -P release clean deploy

$ mvn -Dtycho.mode=maven nexus-staging:release

</pre>

This will clean the sources, compile everything, create packages, install them in the local maven repository and finally deploy the *fr.irit.smac.may.speadl.parent* and *fr.irit.smac.may.speadl* modules to Maven Central.

Note that to deploy to Maven Central, it is needed to:

* Have a Sonatype JIRA account linked to "this ticket":https://issues.sonatype.org/browse/OSSRH-12012 as explained on "this page":http://central.sonatype.org/pages/ossrh-guide.html.

* Have a GnuPG key to sign the packages as explained on "this page":http://central.sonatype.org/pages/requirements.html and "this page":http://central.sonatype.org/pages/apache-maven.html.

The @-P release@ argument is important so that the deployed artefacts have a source and javadoc associated artefact and are signed as needed by Maven Central.

The @nexus-staging:release@ goal must be called to actually accept the deployment and release it on Maven Central: that last phase can also be done "trough the Nexus UI":http://central.sonatype.org/pages/releasing-the-deployment.html.

h2. Deploying the Release in the Update Site

The update site contains all releases of MAY, not just the last one: in order to add a new version, it is first needed to get the current update site, to add the plugins and features, and finally to update some metadata in it.

h3. Getting the Current Update Site

The update site of MAY is stored on the IRIT servers.

A copy must be made locally, for example using SSH and rsync:

<pre>

$ rsync -azv -e "ssh USER@sash.irit.fr ssh" USER@bali:/REMOTE/PATH/TO/UPDATE/SITE /LOCAL/PATH/TO/UPDATE/SITE

</pre>

Or directly by mounting it through SSH:

<pre>

$ sshfs USER@bali:/REMOTE/PATH/TO/UPDATE/SITE /LOCAL/PATH/TO/UPDATE/SITE

</pre>

The choice of the method is out of the scope of this document, the important point is to have a locally accessible directory of the existing update site.

h3. Add New Version to Update Site and Update Metadata

Use the following to update the update site with new version:

<pre>

$ cd ../fr.irit.smac.may.speadl.updatesite

$ mvn -Dtycho.mode=maven -Dfinal-update-site=/LOCAL/PATH/TO/UPDATE/SITE tycho-p2-extras:publish-features-and-bundles tycho-p2:category-p2-metadata 

</pre>

h3. Publish the New Update Site

If the update site was copied using rsync, it is needed to sync it back, for example with:

<pre>

$ rsync -azv -e "ssh UGER@sash.irit.fr ssh" /LOCAL/PATH/TO/UPDATE/SITE USER@bali:/REMOTE/PATH/TO/UPDATE/SITE

</pre>

If it was mounted through SSH, nothing has to be done except unmounting if desired:

<pre>

$ fusermount -u /LOCAL/PATH/TO/UPDATE/SITE

</pre>

Again, this is out of scope of this guide.

h2. Preparing the Next Development Cycle

Now everything is deployed, we can prepare the next development cycle by increasing the version to a SNAPSHOT one.

Because we changed only the version of the POM file and not the version of the MANIFEST file, it is needed first to revert the version change and then increment the versions all at once:

<pre>

$ cd ../fr.irit.smac.may.speadl.parent

$ mvn -Dtycho.mode=maven versions:set -DnewVersion=3.4.0-SNAPSHOT

$ mvn -Dtycho.mode=maven org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=3.4.1-SNAPSHOT

</pre>

And then, we can commit it and push all the changes we made:

<pre>

$ hg commit -m "increment to 3.4.1 development version"

$ hg push

</pre>