|
|
 Doing an Apache UIMA™ Release
|
These instructions are for the 2.3.1 and later releases, as a top level project.
A previous version of this page, with the methods we used while in the incubator, is
here.
Once you've done it a few times, you may find the shorter
release checklist more convenient.
Release Overview
|
The UIMA project mainly releases:
- The UIMA SDK
- UIMA-AS add-on
- Individual Annotators, tooling, and other useful components (like the Simple Server)
In addition, it releases some Maven build tooling components that
need to be in the Maven repositories to support our Maven processes.
Releases show up in the Maven central repository and/or
as downloadable artifacts listed on our downloads pages.
|
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, if it is
complex.
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/UIMA/release-plan.html
|
Preparing the Jira for the Release
|
The build includes a generated set of Jira issues fixed (closed or resolved) in this release.
To make this accurate, go through the Jiras and ensure the ones you are including in the release
are closed/resolved, 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.
These are normally updated automatically when the previous release is done.
-
Make sure that any README files have been updated with the latest release information
and release numbers.
-
Update the release notes for the release.
- Edit the POM of the top level thing being released, to add the property:
<jiraVersion>123456</jiraVersion>
replacing the 123456 with the actual Jira internal version number
(or numbers, separated by a comma) for the Jira release(s) being
done. This value is used during release processing to automatically
generate a report of the list of Jira issues that are included in this release.
Change "123456" to be the actual jira internal version number, which you can get
from the Jira url (see parameter fixfor=xxxxxx or fixforversion=xxxxxx)
by going to https://issues.apache.org/jira/browse/UIMA
and selecting "Releases" or "Versions" and then going to the
particular version and looking in the url for
that version.
You can also generate this report manually (for instance, if you want to
have a look at what it will produce) by going to top level project
being released (e.g., uimaj-distr) and issuing the maven command:
mvn changes:jira-report -N
Each time this plugin is run, it creates an updated report in the
top level of this project. This report doesn't need to be checked into SVN.
It will be regenerated and copied into the distribution archives (source and binary)
during a release. The RELEASE_NOTES.html files have been updated to
refer to this generated report.
Running the mvn release... command will cause this report to be generated or
updated, every time the command is run. So it is important that the POM
is updated to include the internal Jira version number, so the
right report is generated.
|
Including updates to the Build tooling
|
This step is skipped, unless the build tooling is being updated.
There are two projects in the build tooling, each having as a parent, the common Apache Parent POM
uima-build-resources and parent-pom.
The following special procedure is used to release updates to these.
The parent-pom has the uima-build-resources's version number encoded as the
"property" <uimaBuildResourcesVersion>XXXXXX</uimaBuildResourcesVersion>
This value will normally be set to the last released version number of the uima-build-resources artifact.
If that artifact is changing, during development, this will be set to the XX-SNAPSHOT value corresponding to
the development version. When releasing, first do a release (to the Nexus Staging repository, as usual) of
the uima-build-resources artifact, which will create a version without the -SNAPSHOT. Then change the
<uimaBuildResourcesVersion> value to correspond to the non-SNAPSHOT version number of this, before
proceeding to release the parent-pom artifact.
|
Building The Release Candidate
|
Prior to releasing, you must do the
one-time setup
required for releasing. Be sure to use a Java 1.5 level, in order to catch
accidental dependencies on later Java features.
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 of the trunk to create the tag. Then it updates the trunk artifacts to the next
version-SNAPSHOT, and commits that.
The release:perform checks out the tag and builds/tests/installs and deploys it to the
NEXUS staging repository.
During this process, 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).
The exception to this is in naming the SVN TAG - normally we have "release candidates".
The recommended convention is to take the suggested name and add "-rc1" for release candidate 1,
etc.
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 a copy of the SVN tag for that artifact, and once unzipped, should be buildable,
using mvn install.
Steps:
- Make sure all changes are checked into SVN. Then check out from SVN the project(s)
you'll be building, into a new "build" location, and do all the building from there.
- Purge your local maven repository of artifacts being built by running in the
top level directory you'll be building from:
mvn dependency:purge-local-repository
Note that this will immediately re-resolve the dependencies from the maven repositories
you have configured.
-
Do a trial build of the release candidate:
cd **directory for doing the release**
mvn install -Papache-release
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.
mvn release:prepare -DautoVersionSubmodules
- take the defaults for the questions, except add -rcN (e.g. -rc1) for the
name of the svn tag - to allow for multiple release candidates
mvn release:perform
Normally, everything built is uploaded to the 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.
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
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 forget to close the repo, it will be open when you do your next
release candidate, and then you'll have in the repo both release candidates, (with
later files overwriting newer), which if any file names have changed, will create
a mess. So be sure to close (and drop as appropriate) any previous repo before starting a release:perform for a new
release candidate, so they deploy into a "fresh" empty staging repo.
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.
|
Tips for the Release Manager
|
The release is done using the commands mvn release:prepare and mvn release:perform.
Having all submodules at the same version:
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:
mvn release:prepare -DautoVersionSubmodules
Trying out the release build: You can build the artifacts that the release would build by using:
mvn package -Papache-release
Re-doing release candidates: There are two ways to reset things back so you can do
another release candidate; depending on how far through the release process you've progressed.
[mvn release:prepare] If you've just done release:prepare,
you can reset things back to as they were before that command by issuing
mvn release:rollback. Check to confirm that the svn tag for the
release candidate is deleted; if not, remove it manually.
[mvn release:perform] If you've done a release:perform, to
reset the source, try doing the release:rollback; this may work if you haven't done a release:clean.
Otherwise,
you have to change the <version>x.y.z-SNAPSHOT> back to their previous value.
You can use Eclipse's search/replace to do this, or the mvn versions plugin.
If you've
"closed" the Nexus repo - you have to drop it. If you haven't, you can just re-run the
release:perform when you're ready, and that will overwrite the staging repo data in Nexus. But see
the next tip.
Nexus staging repositories and your source computer The staging repo that
receives the output of mvn release:perform has as part of its name, the
IP address where the deploy comes from. If you have a laptop, and do part of the release
at "work", and then another part at "home", the IP address will be different, and
multiple staging repositories will be created. This is not a problem, usually, unless
you are updating a release by redoing it, and are expecting the previous version
to be overwritten. In case it isn't, you can just use the Nexus command line interface
to delete the old version from the "other" staging repo.
|
Removing -SNAPSHOT dependencies
|
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.
|
Stage the (partial) eclipse-update-site
|
- Build the Eclipse update site, after the corresponding jars have been staged
with their final release numbers to the staging repo:
- Edit the site.xml to include any new features, with the final release numbers.
- run
mvn package on the uimaj-eclipse-update-site project
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.
|
Doing The Release Vote
|
The release candidate typically consists of
- assembly source and binary distributions,
- the associated SVN tag, and
- the individual Maven module artifacts.
The source and binary distributions are manually copied by the
release manager to the release manager's people.apache.com
account, 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 SVN tag corresponding to the release, and
if needed, the place on people.apache.org 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).
For an example, see this dev-list post.
|
Releasing
|
After a successful release vote for the release on the dev mailing list:
- Promote the release(s) from the staging repositories:
log on to the staging repository again, and release the staged artifacts.
This will make the artifacts available in the Maven Central repository.
Upload the release artifacts from people.apache.org to the distribution server
(via copying on people.apache.org
to the directory: /www/www.apache.org/dist/uima, including the
release artifacts and the Eclipse update site data (which are merged with
the existing previous plugin releases already on the update site).
Be sure to include the asc/md5/sha1 signatures.
Make sure the KEYS file in that uploaded directory is current (master located in
SVN uima/site/trunk/uima-website/docs/KEYS). Additionally it is necessary to 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.
- Things not needed to be mirrored go into our website:
on p.a.o, in directory www/uima.apache.org/d/
Currently, this includes the RELEASE_NOTES (plus issuesFixed) for the release,
the new docbooks, and the Javadocs.
Before, things only got to our website by being added to SVN. Apache Infrastructure has
set up an additional path for our project to allow large generated objects (e.g., Javadocs)
to bypass SVN. This works as follows: Anything you want on our website can be put in
people.a.o in the directory www/uima.apache.org/d/, just by copying it there. This location
will be rsync'd to our website once an hour, approximately.
Copy released artifacts to targets: bin, src, to p.a.o/www/www.apache.org/dist/uima,
new features / plugins from Eclipse update site target/eclipse-update-site to .../dist/uima/eclipse-update-site
(add to what's already there).
- 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.
Update the Eclipse site and digest as needed.
- 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 p.a.o/www/uima.apache.org/d/[project-version].
- After the distribution directory on people.apache.org/www/www.apache.org/dist/uima is updated,
update the downloads page of the web site
- Update Jira version info to reflect the release status and date
- Rename the SVN tag for the release candidate if it ends in -rcXXX, without the -rcXX to indicate the release.
- After release appears on maven central, post an appropriate announce letter
- Add release to next Board report
|
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.
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.
|
|
|
