:doctype: book

Title: ReleasingAries

+++<a name="ReleasingAries-HowtodoanAriesRelease">++++++</a>+++

= How to do an Aries Release

There are three types of Aries release:

. Releasing a single Aries bundle (or group of bundles)
. Releasing a distribution - a group of bundles that work together
. Releasing the samples

The outline process is the same in all three cases, further on down this page there are details about how the Apache release process works and how to get set up to run it, read those sections first if this is  your first release.
If you are already familiar with the Apache process just use the high level descriptions in the next few paragraphs to perform releases.

== Releasing a single bundle or group of bundles.

=== What to release? Make a list

The Apache release process will not release any bundle that has dependencies on -SNAPSHOTS.
If, for example, a release of the blueprint API bundle is required the first step is to find and release any of its -SNAPSHOT dependencies.
Because Aries bundles are quite interdependent (see link:moduledependencies[here]  for an idea of how the modules relate to each other, it may be necessary to release quite a large number of bundles.
So, step one is to make a list.

=== Choosing a strategy for the release

Even when releasing a large number of bundles, in Aries we release bundles individually.
If there are dependencies between the bundles you want to release, you have four strategies for how to release them.

* *Release incrementally.*
 ** Release bundles in dependency order, updating dependencies only after releases are promoted.
 ** This has the advantage that trunk always builds cleanly.
 ** The disadvantage is that each release needs to be open for voting for at least 72 hours, so the elapsed time for a large release can be very long.
 ** The list may get fed up of voting on multiple vote threads, although the http://aries.apache.org/development/verifyingrelease.html[verification script] may help.
* *Release all at once, then patch up trunk, then fix trunk*
 ** Release api bundles release and have them uploaded to nexus, then upgrade the implementations  and all other components to use those releases, commit,  release those other projects, then close the staging repo and call for a vote.
 ** Bundles in the staging repo will need to compiled in a set order, which makes the verification script less useful.
 ** Trunk will be broken, unless you back out everything which you changed to use the released version back to using the old snapshot (_not_ the new snapshot created by the release plugin).
Then once the release has been promoted, change everything using the old snapshot back to using the released version.
 ** Doing a release this way can really reduce the amount of time spent waiting for votes.
 ** However, getting everything right without breaking trunk can be complex.
* *Release all at once, and use profiles to keep trunk building*
 ** This is similar to the second procedure, except instead of backing everything out, you just provide a maven profile which people can use until the release is promoted
 ** Once the release is promoted, cleaning up is easy - just delete the profile
 ** You will also need to temporarily change the Jenkins build instructions
 ** If people don't notice they need to build using a profile, they may be confused about why things are broken
* *Release from a branch*
 ** This is similar to the second procedure, except there's no need to patch trunk up to keep it compiling
 ** You will need to merge the branch across once the release has been promoted, which is extra complexity
 ** Doing mainline releases from branches plays havoc with git mirroring, so we promised to try and avoid doing it
 ** See below for extra instructions on releasing from a branch

In many cases with semantically versioned bundles there won't be dependencies on the latest and greatest snapshots, which makes everything much easier.

=== How to deal with JIRA

Before actually doing any releasing work through the list of bundles and understand what defects have been fixed (add more about JIRA versions here)

=== What version will be released?

For each bundle on the list check how its package versions have changed since the last release.
Based on this, use the link:versionpolicy[versioning policy] to determine the version of the bundle that should be released.

=== Releasing bundles

For each bundle:

* Deploy a SNAPSHOT to the maven snapshot repository (mvn deploy)
* Build each module and run RAT checks
* Create the release artifacts (mvn release:prepare)
* Upload release artifacts to a staging repository (mvn release:perform)

=== Complete the process

Once the bundles are in the staging repository, start a vote on the release.
After 72 hours close the vote.
To complete the release process it is necessary to copy the new bundles to the dist dir and update table on the web pages.

== Releasing a distribution

A distribution is just a collection of Aries bundles which have already been released.
The distribution is just a convenient way for consumers to download aries bundles and all of the Aries bundles that they depend on.
There are three distributions:

* Blueprint
* Application (isolating framework)
* Application (non-isolating framework)

The release process is just the same as for everything else, again, the right time to release these is immediately after a bundle(s) release when you have a collection of artifacts that  work together.

== Releasing the samples

The Aries samples are designed to work across all the Aries modules.
Samples are released as a single module.
All of the Aries dependencies are listed in the top level samples pom.
_It is very important the versions are set *only* in the top level  sample pom_.
Both sub-modules and filtered resources need the version information, setting it in one place is the only way to avoid a mess.

The best time to do a samples release is usually at the end of a bundle release.

It is critically important that the samples are all tested before making release.
Some have itests but others (blueprint) are only tested manually.
In fact it's wise to run through a quick manual check for the blog and aries trader samples as the itests do not catch everything.

= Background information on the Apache Release process

To create a release you will need to create the release artifacts and move then to various places (ultimately the Maven central repository).
The Maven commands and general outline of the process looks like this:

image::AriesRelease.png[rel]

The full maven commands are not shown - the intention is just to give an indication of which maven commands you will need to use to create release artifacts in different places.

Performing a release is described in detail http://apache.org/dev/publishing-maven-artifacts.html[here] . This document It covers all the steps listed above so on these pages we will only add things which are specific to the Apache Aries release.

There are a few steps to the process:

. Discussion of the release and its content on the dev@aries mailing list.
. Creating and storing GPG keys
. Setting up your environment
. JIRA preparation
. Checking the release version of the bundle
. Checking release artifacts on your local system
. Creating a snapshot release
. Releasing to a staging repository (uses mvn release:prepare and mvn release:perform)
. Running a vote
. Promoting the release artifacts to the Apache release repository
. Making the release artifacts available from the Aries web pages
. What to do when people find problems with the release artifacts

The best current documentation for releases is http://apache.org/dev/publishing-maven-artifacts.html[here].
It covers all the steps listed above so on these pages we will only add things which are specific to the Apache Aries release.

+++<a name="ReleasingAries-Discussionofthereleaseandit'scontentontheAriesmailinglist">++++++</a>+++

[discrete]
=== Discussion of the release and its content on the Aries mailing list

Before starting off the release process it is essential to gain consensus on the dev@aries list that this is the right time for a release and to agree its content.
Allow at least a week for this discussion.

+++<a name="ReleasingAries-CreatingandstoringGPGkeys">++++++</a>+++

[discrete]
=== Creating and storing GPG keys

For Aries your GPG key will need to be in this file: https://svn.apache.org/repos/asf/aries/KEYS (follow the instructions in the file) and checkin.
Then ensure the file is mirrored to http://www.apache.org/dist/aries/KEYS by following the instructions http://www.apache.org/dev/release.html#upload-scp[here].

+++<a name="ReleasingAries-Settingupyourenvironment">++++++</a>+++

[discrete]
=== Setting up your environment

Follow the general instructions linked to above.

+++<a name="ReleasingAries-Creatingabranchtoreleasefrom">++++++</a>+++

[discrete]
=== Creating a branch to release from (if needed)

It is strongly recomended that releases are made from trunk and NEVER from a branch.
But, if you have to release from a branch this is what  you will need to do:

....
svn copy https://svn.apache.org/repos/asf/aries/trunk \

https://svn.apache.org/repos/asf/aries/branches/0.X-RCx \

  -m "Creating a release branch of /aries/trunk."
....

Where '0.X' is the number of the release.

Checkout the new branch, for example, for the 0.2-incubating  release:

 svn co https://svn.apache.org/repos/asf/aries/branches/0.2-RCx aries-0.2-candidate

_IMPORTANT_ If you are using a branch to release you *must* edit the  pom.xml for *each* bundle to change the SCM references to point to the branch and not to trunk.
For example:

 <connection>scm:svn:http://svn.apache.org/repos/asf/aries/branches/0.2-RCx/parent</connection>

 <developerConnection>scm:svn:https://svn.apache.org/repos/asf/aries/branches/0.2-RCx/parent</developerConnection>

 <url>scm:svn:http://svn.apache.org/repos/asf/aries/branches/0.2-RCx/parent</url>

The consequence of forgetting this is that the commands that create the release (mvn release:prepare, mvn release:perform) will declare SUCCESS but will not create a staging repository and will add stuff to the snapshot repository :-/.

After taking the branch, change the pom versions in trunk to, say, 0.3-incubating or whatever you want to call the next development version.

+++<a name="ReleasingAries-Checkingbundleversion">++++++</a>+++

[discrete]
=== Checking which version of the bundle to release

If the Maven version of the bundle ends -SNAPSHOT then some change has been made which may require a release.
To get a summary of the changes, use svn to compare with the most recently released tag,  for example:

  svn diff https://svn.apache.org/repos/asf/aries/tags/testsupport-0.3/  https://svn.apache.org/repos/asf/aries/trunk/testsupport/ --summarize

In general, if no Java files have changed only the micro version of the bundle will need to be incremented on release.
If Java  code has changed it is important to check the packageinfo files to see whether package versions have changed.
If so these might lead to the requirement to increment the major or minor versions the bundle.

+++<a name="ReleasingAries-Checkingreleaseartifacts">++++++</a>+++

[discrete]
=== Checking release artifacts

Delete everything under ...org/apache/aries in your local Maven repo.
For linux/Mac users you will find this under ~/.m2/repository/.

Check that the code builds using the usual link:buildingaries.html[sequence]  of commands, but add the following arguments to the 'mvn install' command:

 mvn install -Papache-release -DcreateChecksum=true

This should build and install release artifacts in your local repo.

Check the https://repository.apache.org/content/repositories/releases/org/apache/aries/parent/0.1-incubating/[0.1 release]  to understand what files should be created.

To perform legal checks, in each subproject, run:

 mvn rat:check -fn

This will run through the project and its sub projects generating a file called rat.txt in each target directory.
The 'fn' means it will carry on even if it find a failure.
To inspect the failures, use:

 find . -name rat.txt | xargs grep \!\?\?

This will pick out the failing file names.
Some of the files that rat fails do not require an Apache license, eg MANIFEST.MF, but any *.java or *.js file does need one.
As an alternative you can use 'mvn -Prat install'.

+++<a name="ReleasingAries-Creatingasnapshotrelease">++++++</a>+++

[discrete]
=== Creating a snapshot release

This is important to do when releasing from trunk as other bundles may want to continue to depend on the -SNAPSHOT version while the release is voted through.

mvn deploy (check exact format)

[discrete]
=== JIRA preparation

* After initial release discussion on the mailing list you should have a list of JIRA issues that are required in the release.
If not, the default assumption is 'everything that has been fixed since the last release'.
* Make sure that there is a JIRA version that matches the name of the release, if not, create one.
* Check through defects, make sure that anything that is included in the release has been closed.
If there are open issues move them to the next release.

+++<a name="ReleasingAries-Creatingtherelease">++++++</a>+++

[discrete]
=== Creating the release

+++<a name="ReleasingAries-Creatingthereleaseartifactsinastagingrepository">++++++</a>+++

[discrete]
===== Creating the release artifacts in a staging repository

The release is created by releasing each bundle separately and in a specific order.
It is also desirable to maintain the same IP address for the entire process (the staging repository is associated with your IP address, changing it results in the creation of a second staging repository).

Short summary: Use a wired ether net connection and allow about 4 hours for the next few steps.

From the top level directory in your branch run:

 mvn clean

_Note_ The prepare step will make some assumptions about the version of the development stream that is left after the release has been made.
When releasing from a branch it may not be a good idea to accept the default for this, it will very likely conflict with the development version in use in trunk.

For each bundle that needs to be release perform the following commands:

 Check that there are no depndencies on -SNAPSHOT versions.
 Ensure that everything is committed in SVN
 mvn release:prepare -Papache-release -DpreparationGoals="clean install" -DwaitBeforeTagging="10" -DscmCommentPrefix="[ARIES-xxx][maven-release-plugin]"
 mvn release:perform -Papache-release

* Note 1: Use the -DdryRun option to check that release-prepare works.
* Note 2: mvn release:prepare makes and commits changes in SVN.
You'll be asked three questions.
Here they are with answers for the 'parent' module release:
 .. What is the release version for "Aries :: Top Parent POM"?
(org.apache.aries:parent) 0.5: :
 .. What is SCM release tag or label for "Aries :: Top Parent POM"?
(org.apache.aries:parent) parent-0.5: :
 .. What is the new development version for "Aries :: Top Parent POM"?
(org.apache.aries:parent) 0.6-SNAPSHOT: : 0.5.1

+
i.e.
take the defaults for the last two questions, but change the release version if required.
The last person doing a release didn't know whether the next version released from the trunk would have a major, minor or micro version number change - they couldn't know until those changes were made!
- but they had to make a guess.
Now is the time  to correct their guess.
Similarly, you won't know what the next release number should be, but you need to use _something_, so accept the default.
* Note 3: Since the release plugin makes changes in SCM, use a JIRA for the release (ARIES-XXX here) in the commit comment to make it easier to see what's changed.
* Note 4: The task will appear to hang at the end.
It's waiting ten seconds to do the tagging, to ensure everything works in Europe, where svn is mirrored from a US master.
* Note 5: mvn release:clean will do _most_ of the cleaning up in the event of failures.
* Note 6: If on mvn release:prepare you get an error from SVN similar to https://svn.apache.org/repos/asf/!svn/bc/1182408/aries/tags/parent-0.5/default-parent/java5-parent/org.apache.aries.bundle.i.am.releasing does not exist then it's because there's no scm element in the pom.xml for the module you're releasing.

This will put release artifacts into an Apache https://repository.apache.org/index.html#view-repositories;staging.html[staging repository].
You will need to log in to see it.
If nothing appears in a staging repo you should stop here and work out why.
If you have made a mistake it's quite easy to revert.
The release commands make and commit changes to the project's pom.xml files and they create a tag in SVN.
To revert the changes you will need to revert the pom.xml files and delete the tag from svn.

+++<a name="ReleasingAries-Closingthestagingrepository">++++++</a>+++

[discrete]
===== Closing the staging repository

After checking that the staging repository contains the artifacts that you expect you should close the staging repository.
This will make it available so that people can check the release.

+++<a name="ReleasingAries-Runningthevote(s)">++++++</a>+++

[discrete]
=== Running the vote.

At this point you should write two notes to the dev@aries.apache.org mailing list.
You may wish to ensure they have slightly different subjects, since googlemail seems to ignore anything in brackets when threading.

* Subject [VOTE]  Apache Aries release candidate 0N

The the source archive files should be explicitly called out by release manager in any release vote.
From an Apache legal standpoint, this is what the project is "releasing" and what the community should be voting on.
In this link:devlistvote.txt[sample note] , there is a link to each modules' source*.zip file.

* Subject [DISCUSS]  Apache Aries  release candidate 0X

The content should just indicate that the note starts a thread to discuss the Aries release.

After 72 hours, if no problems have been found in the release artifacts, the dev@aries vote can be summarised and closed.
Note that at least three +1 votes from Aries PMC members are required.

+++<a name="ReleasingAries-Promotingthereleaseartifacts">++++++</a>+++

[discrete]
=== Promoting the release artifacts

From the https://repository.apache.org/index.html#stagingRepositories[Nexus pages] , select the staging repository and select 'release' from the top menu.
This moves the release artifacts into an Apache releases repository, from there they will be automatically moved to the Maven repository.

+++<a name="ReleasingAries-MakingthereleaseartifactsavailablefromtheArieswebpages.">++++++</a>+++

[discrete]
=== Making the release artifacts available from the Aries web pages.

Anything that is to be downloaded must be put in /www/www.apache.org/dist/aries on minotaur.
Don't forget to changes the file permissions to '664' so that other  members of the group can access them.
The distributions are archived here /www/archive.apache.org/dist/aries.

First, delete the artifacts of the previous release from the distribution directory.
You don't need to worry about putting the previous release artifacts in the archive as they will already have been rsync'd from the distribution directory.

Then, put new release artifacts in the distribution directory.
This is best done using a script, the script can be generated using the perl script http://svn.apache.org/repos/asf/aries/scripts/download_release_artifacts.pl[download_release_artifacts.pl].

Next, update the Aries Downloads pages to refer to the new artifacts.
The the perl script http://svn.apache.org/repos/asf/aries/scripts/create_modules_table.pl[create_modules_table.pl] can do this automatically.

[discrete]
=== Updating dependencies

Once the release is promoted, change all the bundles which depend on the SNAPSHOT to depend on the released version.
Deployed snapshots get regularly cleaned from the repositories if there's a released version available, so building against them isn't reliable.

Don't move bundles which depend on earlier releases to depend on the new release, or they won't be able to run in an environment with the older bundles.

[discrete]
=== Tidying up tasks

* Get the http://aries.apache.org/development/compliancetesting.html[compliance tests] run
* Release notes
* Release the component in JIRA (manage components), check the JIRA release notes.

+++<a name="ReleasingAries-Whattodowhenpeoplefindproblemswiththerelease">++++++</a>+++

[discrete]
=== What to do when people find problems with the release

* Cancel the vote [CANCELLED] [VOTE]
* Clean up, fix and re-release.
The good news here is that it isn't necessarily essential to re-release every module.