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, Tycho for the integrating Eclipse aspects with Maven and some Bash scripts.

h3. Modules

MAY is decomposed in 5 different software modules (which are to 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

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

We just finished developing the 3.4.0-SNAPSHOT version and want to release the new 3.4.0 version.

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@ part of the line 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.

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

</pre>

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

See "this page":http://central.sonatype.org/pages/requirements.html for more information on these matters.