UIMA project logo
Doing an Apache UIMA Release
Apache UIMA

Search the site

 Doing an Apache UIMA™ Release

These instructions are for the 2.3.0 release. For the 2.3.1 and later release, please see this page.


Release Discussions - Release Plan

At the beginning of the "UIMA Release Process" there must be consensus in the developer community about the JIRA issues that should be part of the next release and the time frame for the release. The result of this discussion should be published in a release plan to the UIMA wiki. This release plan should be kept up-to-date any time so that everybody can have a look at the target dates to calculate personal ToDos.

The previous UIMA release plans and a release plan template are available in the UIMA wiki at http://cwiki.apache.org/confluence/display/UIMA/release-plan.html

Preparing the Jira for the Release

In a following step, you will extract from Jira the set of issues fixed in this release. To make that work, go through the Jiras and insure the ones you are including in the release are closed, and that the "Fixed in release xxx" is set for each Jira issue that is part of the release.

There is a saved "filter" you can adjust for this that will display all fixed Jira issues with no Fixed in release xxx assigned. You can go through subsets of this (use the filter to pick the subset you want) and do "bulk Jira changes" to update multiples of these in parallel, if that makes sense.

Preparing The Sourcecode For The Release

Before the source code can be tagged for the release check the points in the list below:

  • Investigate versions of things using

    mvn versions:display-dependency-updates
    mvn versions:display-plugin-updates and
    mvn versions:display-property-updates


    Use this information to update to later versions, if appropriate.
  • Make sure that each release artifact that should be released has the correct version number. There is an ant build script you can run here: uimaj-distr/src/main/build/changeVersion.xml. To run it, first edit the file versions.properties in the same ... / build directory, setting the "previous" version (the current version info in the source), and the "new" version that it should be set to. Then, cd to uimaj-distr/src/main/build and do ant changeVersion.xml to run it. It checks the following places for correct versions.
    • uimaj project: POM.xml
    • uimaj child projects: check version for the parent POM
    • uimaj plugin projects (uimaj-ep-...): MANIFEST.MF
    • uimaj-core project: UIMAFramework_impl.java
    • uimaj-dist project: ReleaseNotes and Readme files
    • uima-docbooks project: common_book_info.xml and index.html
    • uimaj Eclipse features
    Some of these things it doesn't update (if the update is complicated); in these case, it will instead, issue a reminder message to you to update things manually.
  • Make sure that the README files has been updated with the latest release information and release numbers.
  • Update both versions (text and HTML) of the release notes for the release. JIRA can provide a list of issues for a certain release when using the 'ReleaseNotes' function.
  • Do a trial build of the release candidate: cd **directory for building the components** mv install cd **directory for creating the distribution** mv install

Building The Release Candidate

All the preparation to build the release candidate is done. In the next step we have to tag the release source code in SVN. Most of time the first release tag isn't the release candidate that is shipped later so we established a simple tag structure where all tags for a release are stored until the final release candidate is found. When looking at the SVN you will find a structure like

uimaj/tags/uimaj-<release version>/uima-<release version>-<tag counter>.
uimaj/tags/uimaj-2.2.1/uima-2.2.1-01.
See Tagging Releases for more info on tagging a release.

After tagging the release the release candidate can be built using the provided build scripts. The release build needs to be built from the tagged version; this avoids getting into the build any changes that might occur subsequent to the tagging event. Further details about how to create the release distribution and how to sign them can be found here. Be sure to sign the release.

Tagging Releases

The UIMA base framework is tagged by using the svn "copy" command to copy the HEAD revision of ..uima/uimaj/trunk to ..uima/uimaj/tags/uimaj-[version-number such as 2.2.2]/[release candidate]

Sub-projects, such as uima-as, are done in a similar manner, but with additional copies as needed if these sub-projects also depend on base UIMA source files. The uima-as sub-project can be tagged by running the tag script in the uima-as-distr/src/main/build directory.

Auditing The Release And Create A RAT report

Releases are now automatically checked using the RAT tool. Any exceptions are recorded in the distribution POM, as part of the configuration for the maven RAT plugin.

There is one exception: the uimacpp release is still separately audited. To audit a uiamcpp the RAT (Release Audit Tool) should be used. Check out the latest version from the website and run the tool on the unpacked release artifacts (binary and source distribution). The command line looks like:

java -jar apache-rat-0.6.jar <release-artifact-directory> > report.txt

The RAT tool generates the audit report and writes it to the report.txt file. Check this file for all lines that start with !????? and add a comment to them saying why they do not have a license header, or fix them so they pass the RAT tests.

Putting release candidates on people.apache.org

The uima-dev community is invited to test the release candidate, and review the RAT reports. To enable them to do this, post the release on your people.apache.org account and notify the uima-dev community via the mailing list where you posted it. Most people post it in ~/public-html/uima-release-candidates/[project-name]/[id-of-release] (e.g. ~/public-html/uima-release-candidates/uima-as/05) so that others can easily download it from the web.

Doing The Release Vote

When all issues are fixed, all test cases are executed successfully and the documentation is up-to-date maybe the release level is found and the release manager can start a release vote on the uima-dev mailing list. With this vote the release manager checks if all committers agree to ship the release level. The vote must be aligned with the Apache vote process.

Ask Incubator PMC To Release

After a successful release vote for the release on the uima-dev mailing list the release is ready for publishing. But before that, the Incubator PMC must approve the release and vote on it. This is necessary since UIMA is still in the Apache Incubator. For details about this approval look at the Incubation Podling Constraints. The vote for the Incubator PMC must be started on the incubator mailing list. The vote mail must contain links to the release artifacts as they will be published, the commented RAT report for the source and binary distribution and a link to the passed uima-dev mailing list release vote.

Publish The Release

After the release is approved, we will have the last tagged release candidate which will correspond to the official release. This should not be updated after this.

  • Build the Eclipse update site:
    • Edit the site.xml to include any new features.
    • Copy from the approved release candidate any new feature Jars to the features directory.
    • Copy from the approved release candidate any new plugin Jars to the plugins directory, after first deleting any Jars that might be there from previous releases.
    • run the ant build script to pack the new plugin Jars, and generate the new site digest containing the new features.
    • run the signEclipseUpdateSite.sh script to sign the new Jars and zip files the build script created. This script can be run on linux or on windows, but on windows, you need to run it inside Cygwin. When you install Cygwin, indicate that it should fixup the windows line ending characters; otherwise the script may not run.
    • Test the result: try using the new site (as a local site) in various versions of Eclipse, and verify it installs OK. If there are errors, correct these and rebuild.
    • SVN commit any changes you did to the trunk. In particular, the uimaj-eclipse-update-site project's features directory, containing any new Feature Jars, is committed, so future site builds have access to this information. The plugins directory content is not committed, because the site build process does not require the plugin information.
  • Upload the release artifacts to the distribution server (via uploading to people.apache.org in the directory: /www/www.apache.org/dist/uima, including the release artifacts and the Eclipse update site data. Be sure to include the gpg/md5/sha1 signatures. Make sure the KEYS file in that uploaded directory is current. Additionally it is necessary to update the download page of the UIMA website to make the new release artifacts available.

    • The Eclipse update site on w.a.o/dist/uima will have previous versions of the jars for the features and plugins. The generated site in uimaj-eclipse-update-site/target/eclipse-update-site has the new version plugin(s) and feature jars. These should be added to the w.a.o/dist/uima update site - leave the others that are already there in place. The other non-jar files should be updated from the generated site.
  • Update the documentation page with the new data on the UIMA website. The mirroring stuff is embedded in the markup - just substitute within that markup the name of the new release (assuming you followed the previous release's nameing conventions for the higher-level directories).

  • Upload the release artifacts to the Maven Incubator repository. To upload, first start up the Pagent server (see below) so that the signon to people.apache.org can proceed. Then go to the project where you built the release candidate, cd to uimaj, and do:

    mvn -DsignArtifacts=true process-resources source:jar deploy

    Before the upload is started, make sure that the Maven settings.xml file is configured properly. It must contain a section like:

    <servers>
      <server>
        <id>staging-repository</id> 
        <username>YOUR_USER_NAME</username>
        <!-- either use password or privateKey authentication -->
        <password>YOUR_PASSWORD</password>
        <privateKey>PATH_TO_YOUR_PRIVATE_KEY_FILE</privateKey>
        <configuration>
          <!-- specify ssh and scp executables (here Putty executables are used) -->
          <sshExecutable>plink</sshExecutable> <!-- use full path to this if not on the path -->
          <scpExecutable>pscp</scpExecutable>  <!-- use full path to this if not on the path -->
        </configuration>
      </server>
    </servers>

    The above configuration assumes you are using PuTTY. PuTTY comes with an executable called PAGENT that you can start prior to running this. When started, it puts up a small icon in your windows icon tray. Right click it, and follow the menu prompts to add your PuTTY key for authenticating while logging into people.apache.org; it will prompt you for your passphrase. Then, when Maven executes the PuTTY commands, PAGENT will automatically provide the passphrase for the key.

    This worked as of 2.3.0 release. In the future try without including the "process-resources" goal, because when done this way, you've already processed the resources as part of building the release candidate. Invoking process-resources will cause rebuilding of the jars. Also, the source:jar will probably not be needed, once the release-build process is fixed to build these automatically.

Announce The Release

To announce the published release send and email to

  • announce@apache.org
  • user@uima.apache.org

and describe the major changes of the release. The email should contain the Apache Incubation disclaimer as long as Apache UIMA is in the incubation phase. Announcements should be posted from the release manager's apache.org address, and signed by the release manager using the same code-signing key as was used to sign the release. For more details please refer to A Guide To Release Management During Incubation.

Our main uima website has a "News" section that should be updated with news of the release.