Chapter 4. Release process

Chapter 4. Release process
Prev		Next

Table of Contents

Release preparation
Prerequisites
Release
Post-release actions
References

Release preparation

The following items should be checked before starting the release process:

Check for the latest Apache parent POM version (artifact org.apache:apache) and if necessary, change the parent of the Axiom root POM.
Check the dependencies between Java packages in the axiom-api module. The org.apache.axiom.util package (including its subpackages) is specified to contain utility classes that don't depend on higher level APIs. More precisely, org.apache.axiom.util should only have dependencies on org.apache.axiom.ext, but not e.g. on org.apache.axiom.om. SonarJ can be used to check these dependencies. The following figure shows the expected structure:

Figure 4.1. Package dependencies for r944680

In contrast, the following figure shows an earlier trunk version of axiom-api with incorrect layering and cyclic dependencies involving org.apache.axiom.util:

Figure 4.2. Package dependencies for r939984

The check can also be done using jdepend-maven-plugin. To do this, execute the following command in the axiom-api module:
```
mvn jdepend:generate
```
Then open target/site/jdepend-report.html and go the the "Cycles" section. The report should not show any package cycles involving org.apache.axiom.mime, org.apache.axiom.util and org.apache.axiom.ext.
Check that the generated Javadoc contains the appropriate set of packages. In particular, unit test related classes should be excluded, except for the test suite classes in org.apache.axiom.ts (we don't need to hide the fact that we have a reusable test suite...).
Check that all dependencies and plugins are available from standard repositories. To do this, clean the local repository and execute mvn clean install followed by mvn site.
Check that the set of license files in the legal directory is complete and accurate.
Check that the Maven site conforms to the latest version of the Apache Project Branding Guidelines.
Check that the apache-release profile can be executed properly. To do this, issue the following command:
```
mvn clean install -Papache-release -Dmaven.test.skip=true
```
You may also execute a dry run of the release process:
```
mvn release:prepare -DdryRun=true
```
After this, you need to clean up using the following command:
```
mvn release:clean
```
Prepare the release note. This should include a description of the major changes in the release as well as a list of resolved JIRA issues. Note that both index.apt and RELEASE-NOTE.txt need to be updated.
Add an entry for the release to the download.xml.vm file and change the links for older releases so that they point to archive.apache.org (Since the Axiom project doesn't use branches and produces releases directly from the trunk, there should only be a single mirrored release).
Preview and validate the changes that will be done by the release plugin to the POM files. In order to do this, execute the following command:
```
mvn release:prepare -DdryRun=true -Dmaven.test.skip=true
```
Next, compare the pom.xml.tag files to the corresponding pom.xml files:
```
for pom in $(find . -name "pom.xml"); do diff $pom $pom.tag; done
```
The differences should be limited to version and scm tags. If necessary, change the original POM files to avoid spurious changes. After that, clean up using:
```
mvn release:clean
```

Prerequisites

The following things are required to perform the actual release:

A PGP key that conforms to the requirement for Apache release signing. To make the release process easier, the passphrase for the code signing key should be configured in ${user.home}/.m2/settings.xml:
```
<settings>
  ...
  <profiles>
    <profile>
      <id>apache-release</id>
      <properties>
        <gpg.passphrase></gpg.passphrase>
      </properties>
    </profile>
  </profiles>
  ...
</settings>
```
The release process uses a Nexus staging repository. Every committer should have access to the corresponding staging profile in Nexus. To validate this, login to repository.apache.org and check that you can see the org.apache.ws staging profile. The credentials used to deploy to Nexus should be added to settings.xml:
```
<servers>
  ...
  <server>
    <id>apache.releases.https</id>
    <username></username>
    <password></password>
  </server>
  ...
</servers>
```

Release

In order to prepare the release artifacts for vote, execute the following steps:

Update the release date in download.xml.vm and index.apt.
Temporarily disable the Jenkins build(s) for Axiom, in order to avoid accidental deployment of the release candidate to the local repository of a Jenkins executor if the release process fails somewhere in the middle and/or a Jenkins build starts at the wrong moment.
Start the release process with the following command:
```
mvn release:prepare
```
When asked for the "SCM release tag or label", override the default value (axiom-x.y.z) by entering a tag in the form x.y.z, which is compatible with the tag names used for previous releases.

The above command will create a tag in Subversion and increment the version number of the trunk to the next development version. It will also create a release.properties file that will be used in the next step.
Perform the release using the following command:
```
mvn release:perform
```
This will upload the release artifacts to the Nexus staging repository.
Log in to the Nexus repository (https://repository.apache.org/ and close the staging repository. The name of the staging profile is org.apache.ws. See http://maven.apache.org/developers/release/apache-release.html for a more thorough description of this step.
Generate and deploy the Maven site on a public Web server. You may use people.apache.org for this.
Start the release vote by sending a mail to dev@ws.apache.org. The mail should mention the following things:
- The list of issues solved in the release (by linking to the relevant JIRA view).
- The location of the Nexus staging repository.
- The location where source and binary packages may be downloaded. This can be a reference to the location inside the staging repository.
- A link to the preview of the Maven site.
Reenable the Jenkins build(s).

If the vote passes, execute the following steps:

Promote the artifacts in the staging repository. See http://maven.apache.org/developers/release/apache-release.html for detailed instructions for this step.
Log in to people.apache.org and publish the release distributions to www.apache.org. The etc/dist.py script can be used for that:
```
cd /www/www.apache.org/dist/ws/axiom
umask 0002
python path_to_etc/dist.py version
```
version is the release version, e.g. 1.2.9.

If not yet done, export your public key and append it to the KEYS file located in /www/www.apache.org/dist/ws/axiom. The command to export a public key is as follows:
```
gpg --armor --export key_id
```

Check out the release tag from Subversion and generate the Maven site. Also check out the existing site:

svn co https://svn.apache.org/repos/asf/webservices\
/axiom/site axiom-site

The existing site needs to be overwritten with the site generated for the new release. This can be done easily using the etc/syncsite.py script (requires Python 2.6). It will copy the files and execute any necessary Subversion commands to add new files and to delete files that no longer exist. After executing the script, commit the changes to Subversion.


	When generating the site, please use a recent JDK version, because some older versions generate broken links.

Log in to people.apache.org and update the site:
```
cd /www/ws.apache.org/axiom/
umask 0002
svn update
```
The umask setting makes sure that other members of the ws group will be able to update the site as well.

It may take several hours before all the updates have been synchronized to the relevant ASF systems. Before proceeding, check that

the Maven artifacts for the release are available from the Maven central repository;
the Maven site has been synchronized to http://ws.apache.org/axiom/;
the binary and source distributions can be downloaded from http://ws.apache.org/axiom/download.cgi.

Once everything is in place, send announcements to users@ws.apache.org and announce@apache.org. Since the two lists have different conventions, audiences and moderation policies, to send the announcement separately to the two lists.

Sample announcement:

Apache Axiom Team is pleased to announce the release of Axiom x.y.z. The release is available for download at:

http://ws.apache.org/axiom/download.cgi

Apache Axiom is a StAX-based, XML Infoset compliant object model which supports on-demand building of the object tree. It supports a novel "pull-through" model which allows one to turn off the tree building and directly access the underlying pull event stream. It also has built in support for XML Optimized Packaging (XOP) and MTOM, the combination of which allows XML to carry binary data efficiently and in a transparent manner. The combination of these is an easy to use API with a very high performant architecture!

Developed as part of Apache Axis2, Apache Axiom is the core of Apache Axis2. However, it is a pure standalone XML Infoset model with novel features and can be used independently of Apache Axis2.

Highlights in this release:

...

...

Resolved JIRA issues:

[WSCOMMONS-513] Behavior of insertSiblingAfter and insertSiblingBefore is not well defined for orphan nodes

[WSCOMMONS-488] The sequence of events produced by OMStAXWrapper with inlineMTOM=false is inconsistent

For users@ws.apache.org, the subject (“Axiom x.y.z released”) should be prefixed with “[ANN][Axiom]”, while for announce@apache.org “[ANN]” is enough. Note that mail to announce@apache.org must be sent from an apache.org address.

Post-release actions

Update the DOAP file (see etc/axiom.rdf) and add a new entry for the release.
Update the status of the release version in the AXIOM project in JIRA.
Remove archived releases from /www/www.apache.org/dist/ws/axiom on people.apache.org.

References

The following documents are useful when preparing and executing the release:

Prev		Next
Chapter 3. `LifecycleManager` design (Axiom 1.3)	Home	Chapter 5. The StAX specification