Chapter 3. Release process
Prev		Next

Chapter 3. Release process

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 that the generated Javadoc contains the appropriate set of packages, i.e. only the public API. This excludes classes from axiom-impl and axiom-dom as well as classes related to unit tests.
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 (by checking that in the binary distribution, there is a license file for every third party JAR in the lib folder).
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 -DskipTests=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
```
Check that the Maven site can be generated and deployed successfully, and that it has the expected content.
Complete the release note (src/site/markdown/release-notes/version.md). It should include a description of the major changes in the release as well as a list of resolved JIRA issues.

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:

If necessary, update the copyright date in the top level NOTICE file.
Start the release process with the following command:
```
mvn release:prepare
```
When asked for the "SCM release tag or label", keep the default value (x.y.z).
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 https://maven.apache.org/developers/release/maven-project-release-procedure.html for a more thorough description of this step.
Execute the target/checkout/etc/dist.py script to upload the source and binary distributions to the development area of the https://dist.apache.org/repos/dist/ repository.
If not yet done, export your public key and append it to https://dist.apache.org/repos/dist/release/ws/axiom/KEYS. The command to export a public key is as follows:
```
gpg --armor --export key_id
```
Delete https://svn.apache.org/repos/asf/webservices/website/axiom-staging/ if it exists. Create a new staging area for the site:
```
svn copy \
 https://svn.apache.org/repos/asf/webservices/website/axiom \
 https://svn.apache.org/repos/asf/webservices/website/axiom-staging
```
This step can be skipped if the staging area has already been created earlier (e.g. to test a snapshot version of the site).
Change to the target/checkout directory and prepare the site using the following commands:
```
mvn site-deploy
mvn scm-publish:publish-scm -Dscmpublish.skipCheckin=true
```
The staging area will be checked out to target/scmpublish-checkout (relative to target/checkout). Do a sanity check on the changes and then commit them.
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 link to the source and binary distributions: https://dist.apache.org/repos/dist/dev/ws/axiom/version.
- A link to the preview of the Maven site: http://ws.apache.org/axiom-staging/.


This step can be skipped if the staging area has already been created earlier (e.g. to test a snapshot version of the site).

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.

Publish the distributions:

svn mv https://dist.apache.org/repos/dist/dev/ws/axiom/version \
       https://dist.apache.org/repos/dist/release/ws/axiom/

version is the release version, e.g. 1.2.9.

Publish the site:

svn co --depth=immediates https://svn.apache.org/repos/asf/webservices/website ws-site
cd ws-site
svn rm axiom
svn mv axiom-staging axiom
svn commit

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

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 https://dist.apache.org/repos/dist/release/ws/axiom/.

References

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

Prev		Next
Chapter 2. Design	Home	Appendix A. Appendix