Make Agents Yourself

h1. MAY Component Library Release Process

{{>toc}}

The component library is a set of projects containing component definitions and implementation to be reused.

They are available through Maven Central for [[MAY Maven Eclipse Setup|use with Maven]].

h2. General Overview

h3. Phases

Releasing the components implies different phases:

# Preparing for the release

# Tagging the release on Mercurial

# Deploying the release on Maven Central

# Preparing the next development cycle

All of this is of course fairly automatised using Maven.

h3. Modules

The library is decomposed in several software modules (which are Maven projects):

* *fr.irit.smac.lib.may.parent*: it contains general Maven instructions shared by the other modules. It inherits from *fr.irit.smac.parent-central*, which contains instructions to release to Maven Central.

* *fr.irit.smac.lib.may.parent-speadl*: it contains general Maven instructions shared by other modules with SpeADL code in it. It inherits from *fr.irit.smac.lib.may.parent*.

* *fr.irit.smac.lib.may.common-interfaces*: it contains Java interface used in the components.

* *fr.irit.smac.lib.may.common-components*: it contains most of the reusable components.

* *fr.irit.smac.lib.may.ivy-distribution*: it contains components to build distributed architectures using the "Ivy software bus":http://www.eei.cena.fr/products/ivy/.

* *fr.irit.smac.lib.may.webservices*: it contains component to build architecture exposing functionality as webservices.

h3. Syntactical Version Numbering

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 non-release (development versions), this is followed  by the SNAPSHOT element (Major.Minor.Patch-SNAPSHOT) that is replaced with the compilation time and date on deployment.

h3. Semantic Version Numbering

The MAJOR and MINOR number follows the numbering of the MAY plugin as explained on that [[MAY Plugin Release Process|page]].

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 parent

$ mvn versions:set -DnewVersion=3.4.0

</pre>

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

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 should 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>

$ cd ../

$ mvn -P release clean deploy

$ mvn 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. Preparing the Next Development Cycle

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

<pre>

$ cd ../parent

$ mvn -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>