Apache UIMA™

Our development branches (i.e. main and maintenance/*) should be protected, so you cannot run a release directly on them. So in order to start a release, first create a release issue to track the release progress and then a corresponding release preparation branch in the repository. Release preparation branches for feature releases should be based off main whereas branches for preparing bugfix releases should be based off a maintenance/XXX branch. Once the release vote is complete, the preparation branch is then merged just like any other pull request.

If README.md file contains version references, update them. E.g. if you have a Maven dependency snippet in there. Optimally, the README.md file should not have any contents that need to change from version to version.

Update the release notes for the release. In particular, include the notable changes (typically all features and bug fixes). You can use this list later for the release announcement mail as well.

Also mention any important changes regarding backwards compatibility.

There may be a [project-root]/src/main/bin_distr_license_notices folder containing LICENSE and NOTICE files which are used for preparing the binary release packages. If the release includes new or updated dependencies bundled in the binary release packages, then these files need to be updated with the respective content from the LICENSE and NOTICE files that may be present in these bundled dependencies (inside the JARs going to the lib) folder.

The Maven release plugin will complain if there are still any SNAPSHOT dependencies being referenced that are not part of the release. However, it will NOT complain if there are still Maven SNAPSHOT repository declarations in the POMs. Check in particular the parent pom for SNAPSHOT repositories and comment them out or remove them.

Update the parent-pom settings for API change reports setting api_check_old_version to the correct previous version to use.

If the release includes Eclipse projects as examples and the release includes also new or updated dependencies, the Eclipse .classpath files in the example projects may need to be updated to include the new libraries.

Purge your local maven repository of artifacts being built by running in the top level directory you will be building from:

Note that this will immediately re-resolve the dependencies from the maven repositories you have configured.

For many multi-module projects, this will fail because it purges things that other modules need. So, the alternative is to just delete the .m2/…​/org/apache/uima/…​` directory on your build machine.

Make sure all changes are checked into source control. Then checkout (not export) from source control the project(s) you’ll be building, into a new build location, and do all the building from there.

If you instead choose to build from your working source control checkout, insure it’s up-to-date with all changes that others may have checked into the release branch.

Do a trial build of the release candidate:

The -Papache-release is used to have the build mimic the build actions that would be taken when the release plugin is running the release build. The -Ddisable-rc-auto-staging ensures that you do not need Subversion and also that you do not (accidentally) stage the release candidate artifacts to the Apache staging area.

The build includes a generated set of issues fixedin this release. To make this accurate, go through the issues and ensure the ones you are including in the release are closed, and that the milestone is set for each issue that is part of the release.

We use the maven-release-plugin to do the releasing. In the prepare phase, it updates the trunk artifacts to remove the -SNAPSHOT suffix, commits it to trunk, and then does an SVN copy or GIT Branch of the trunk or master to create the tag. Then it updates the trunk artifacts to the next version-SNAPSHOT, and commits that.

The release:perform goal checks out the tag and builds/tests/installs and deploys it to the NEXUS staging repository.

During release:prepare, the release plugin asks what the next levels should be and what the tag name should be, and unless there’s a good reason, we take the defaults (by just hitting enter).

When releasing a multi-module project where all the submodules have the same release version as the root project (e.g., uimaj-distr), you can have the release plugin set the version for all the submodules the same value as the root, automatically, just use this form of the release:prepare:

In the past, we added a suffix representing the release candidate to the tag, e.g. -rc1 for release candidate 1, etc. However, the URL for this tag becomes part of the released POM. After a successful vote, we would have upgraded the release candidate to the final release by renaming the tag in source control. At that point, the URL in the POM would have become invalid. For this reason, it was decided to NOT add the -rc1 to the tag anymore.

The release plugin automatically signs everything that needs signing using gpg. It also builds the sources.jar, and one overall (for multi-module projects) source-release.zip file, which can be later obtained and should be an (approximate) copy of the tag for that artifact, and once unzipped, should be buildable, using mvn install.

Normally, everything built is uploaded to the Apache’s Nexus Staging repository. However, for the (large) distribution objects, such as the source and binary distributions for UIMA Java SDK etc., the "deploy" step is skipped. These artifacts, instead of being "distributed" using the Maven central repository, are distributed using the Apache Mirroring System.

POMs can refer to other artifacts in several ways, for example via the <parent-pom> element, or via a <dependency> element. Often, a release will involve releasing together multiple modules (all at -SNAPSHOT levels) that refer to one another using these elements. When that happens, the references in these two elements are automatically updated during the release process, from xx-SNAPSHOT to xx for the tag, and then to the next development level, for the trunk.

Exception to this: -SNAPSHOT suffixes are not updated for references within plugins.

Note that any JARs, Zips, Tars, tar.gz artifacts must be signed by the Release Manager. When -Papache-release is active, the GPG Maven Plugin runs and signs the artifacts with the user’s default GPG key. If you have multiple keys on your system, make sure to switch default to the right key before the release.

You can upload to the Nexus Staging repository several independent artifacts; they will all get added to the same unique temporary staging repository Nexus creates. Once all the artifacts are in place, you log into https://repository.apache.org using your ASF LDAP credentials, go to your staging repository, and close the repository. After that, nothing more can be added. If you deploy another artifact, it will create a new staging repository.

If you have several artifacts to release, and you want subsequent artifacts to depend on the released versions of earlier ones, you can do this, by releasing the first one, then releasing subsequent ones that depend on that, etc. This works because the first one you release will get built with the release version and installed to your local repository, as well as the Nexus staging repository. So subsequent ones that depend on the release version of previous ones, will find that in your local repository.

If you forget something and close the staging repository too soon, just continue as if you hadn’t. Subsequent release artifacts will go into another newly created staging spot on Nexus. The downside of this is that you’ll have to tell the voters about multiple staging repos.

The release candidate typically consists of

The source and binary distributions are manually copied by the release manager to the Apache distribution SVN in the dev/uima spot, to make them available for review. The Maven module artifacts are found in the Nexus staging repository, and are available once the release manager "closes" the repository.

After things are staged, you write a note to the dev list, asking for an approval vote. You need to provide the url(s) of the closed staging repository in the note so the approvers can find the code to check, the source control tag corresponding to the release, and if needed, and the place in the distribution SVN where the source and binary distributions being proposed are found. The [VOTE] email should be based on similar previous votes, and include instructions to testers on how to set up their maven settings.xml file to specify the particular staging repository (or repositories, if more than one is being used).

Before casting +1 binding votes, individuals are REQUIRED to download all signed source code packages onto their own hardware, verify that they meet all requirements of ASF policy on releases as described below, validate all cryptographic signatures, compile as provided, and test the result on their own platform.

Source: https://www.apache.org/legal/release-policy.html#release-approval

First we fetch the staged artifacts from the ASF staging spot as well as from the ASF Maven staging repository. If there is an Eclipse update site, it should be included under the ASF staging spot.

All files (except hash files,detached signatures, or a few files like maven-metadata.xml or 'LICENSE' etc.) should have a detached signature. Check that this detached signature exists and validates against the file.

For the same set of files for which we checked the signatures, also check the SHA512 hashes are valid.

Checking SHA1/MD5 files generated by the Maven Repository is a bit tedious because the hashsum files do not contain the filename and so the sha1sum and md5sum checking functionality does not work. We have to do set up a little script to help us.

Typically, we have Maven projects, so this would running a Maven Build

For more information on the ASF release policy, please see the Apache Release Policy document.

Send an email to the developer mailing list indicating your vote.

For more information, please refer to the Apache Voting Process.

The staging spot and the release spot are in the same (large) ASF Subversion repository. So instead of uploading the artifacts again, we can simply copy them from the staging spot at https://dist.apache.org/repos/dist/dev/uima/ to the proper locations under https://dist.apache.org/repos/dist/release/uima/.

Note that the Eclipse Update Site which was a subfolder in the staging spot must now be copied to the proper location in the P2 composite update site.

Tags starting with rel/ should be protected in all Apache UIMA git repositories. By prefixing the release tag with rel/, you make sure the tag cannot be accidentally deleted.

Merge the release preparation pull request just like any other PR via the GitHub website.

Update the download page of the UIMA website to make the new release artifacts available. This is done indirectly, by editing both the downloads.xml page and also by adding entries to the xdocs/stylesheets/project.xml page - follow the previous examples.

Also, things not needed to be mirrored go into our website: in the docs/d directory. Currently, this includes the RELEASE_NOTES (plus issuesFixed) for the release, the new documentation, and the Javadocs.

Copy RELEASE_NOTES and issuesFixed from the top level project (where the mvn release:perform was done from) in the directory target/checkout/ …​ to the the website in docs/d/[project]-current. The documentation for the latest release should always be in the [project]-current folder. A copy of that should be created under project-[version].

Our main UIMA website has a News section that should be updated with news of the release. There are 2 place to update: One is the index.xml file, which has a one-line summary (at the bottom) that references a link within the new.xml page; and a new entry in the news.xml page itself. Follow previous examples.

Update Jira version info to reflect the release status and date

After release appears on maven central, post an appropriate announce letter.

To announce the published release send and email to

and describe the major changes of the release. 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.