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 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 3.1. Package dependencies for r944680

    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 3.2. Package dependencies for r939984

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

  • 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).

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><!-- KEY 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><!-- ASF username --></username>
        <password><!-- ASF LDAP password --></password>
      </server>
      ...
    </servers>

Release

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

  1. Update the release date in download.xml.vm and index.apt.

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

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

  4. Perform the release using the following command:

    mvn release:perform

    This will upload the release artifacts to the Nexus staging repository.

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

  6. 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
  7. 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
    [Tip]

    This step can be skipped if the staging area already exists and is in a state where it can cleanly be merged.

  8. Stage the site as described here. Note that the commands must be executed in the target/checkout directory.

  9. 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/.

  10. Reenable the Jenkins build(s).

If the vote passes, execute the following steps:

  1. Promote the artifacts in the staging repository. See http://maven.apache.org/developers/release/apache-release.html for detailed instructions for this step.

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

  3. Publish the site:

    svn merge \
     https://svn.apache.org/repos/asf/webservices/website/axiom-staging \
     https://svn.apache.org/repos/asf/webservices/website/axiom

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

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

References

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