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