Release Process

Every project needs a release process. This document is based on an email here.

Here are some references for fleshing out this process.

• The overarching Apache release process .
• Guidance on Apache Incubator release process.

Release contents

API

• kato.api - The API interfaces and the services framework
• The JSR-326 specification.
• TCK - harness and tests.

Implementations

• kato.cjvmti - The JSR-326 API JVMTI implementation
• kato.native.cjvmti - The JVMTI agent.
• kato.hprof - The implementation of JSR-326 API for hprof.

Tech demos:

• kato.jdi - The JDI connector
• kato.tools.katoview - The command line tool.

Release naming policy

The releases will be versioned like "Mx-incubating" where "x" is the number of the release. The "M" stands for "Milestone" meaning that it is not a complete release, and the "incubating" component is there until the project is either cancelled or graduates to a top level Apache project.

Packages will therefore start "apache-kato-Mx-incubating".

After the milestone releases are agreed to have been complete, we will move onto versions of the format "x.y-incubating". Starting at 1.0-incubating.

Instructions for producing a release

These are the steps to perform when creating a release. The release version in this example is "M2-incubating". Please update as appropriate.

The release consists of pure Java and native packages. The native packages are built for Windows x86 and Linux x86.

Prerequisites

You will need:

• Sun's 6.0 JDK
• maven 2.2
  This is the version we are using, earlier version may be ok.
• GnuPG 2
  See here for instructions on managing keys. Version 2.0.13 is recommended for key generation.
• GCC and C library headers
• Microsoft Visual C++
  Currently version 6.0 is being used.

Please ensure the JAVA_HOME environment variable is set to the JDK location.
MAVEN_OPTS=-mx512m can be set if maven fails because of an OutOfMemoryError

Java packages

1. Check out the trunk:
   svn checkout https://svn.apache.org/repos/asf/incubator/kato/trunk/
2. Change the release name. This will have to be done for all of the pom.xml files. For example, to change the versions from M1-incubating to M2-incubating:
   find -name 'pom.xml' -exec sed -i "s/M1-incubating/M2-incubating/g" '{}' ';'
3. Check the pom.xml files back in.
4. Create a branch. This allows any minor changes necessary for the release to be made without fear of picking up unwanted changes being made on trunk, and without needing to prevent changes to the trunk. To do this, enter the following:
   svn copy -m "Branch for M2-incubating" https://svn.apache.org/repos/asf/incubator/kato/trunk/ https://svn.apache.org/repos/asf/incubator/kato/branches/M2-incubating
5. The source should then be checked out like so:
   svn checkout https://svn.apache.org/repos/asf/incubator/kato/branches/M2-incubating
6. Currently the build has two directories - org.apache.kato and org.apache.kato.eclipse. The eclipse build is currently not released. To perform the build:
   cd M2-incubating/org.apache.kato; mvn clean install
7. After the build has been completed, the contents have to be packaged. To do this:
   cd kato.distro; mvn assembly:assembly
8. The packages will be present in M2-incubating/org.apache.kato/kato.distro/target. These should be copied to a separate directory for preparation for the release. For this example, release/

Native Packages

These packages have to be built separately on Windows x86 and Linux x86. You will probably be able to this on the same machine as the Java package build for one platform.

1. Checkout the branch, same as before.
2. Change directory, and build the native packages:
   cd m2-incubating/org.apache.kato/kato.native
mvn install
3. Then create the native packages:
   cd m2-incubating/org.apache.kato/kato.native.distro; mvn assembly:assembly
4. Copy the generated packages (perhaps from another machine) from kato.native.distro/target to the release/ directory.

Checksumming, signing

Some files must be generated before the files are uploaded to the download site.
See here for details on signing http://www.apache.org/dev/release-signing.html.
The signing should not be performed on Apache servers.

1. Change directory to your release/ directory.
2. Generate the md5 checksums:
   ls *.tar.gz *.zip | xargs -n 1 sh -c 'md5sum $0 >$0.md5'
3. Generate the SHA512 checksums:
   ls *.tar.gz *.zip | xargs -n 1 sh -c 'gpg2 --print-md SHA512 $0 > $0.sha'
4. Sign the packages. You should consider running a gpg-agent server, otherwise you will be prompted for the key passphrase each time :
   ls *.tar.gz *.zip | xargs -n 1 sh -c 'gpg2 --armor --output $0.asc --detach-sig $0'

Generate RAT reports

The RAT "Release Audit Tool" generates a report of the contents of files to ensure that the licenses and notices are correct for an Apache release. This should be run against the contents of the source and binary releases, and they should be placed with the packages when they are being reviewed. However, they don't form part of the release itself and shouldn't be distributed with the packages themselves.

1. Download and install the RAT. Follow the instructions from here: http://incubator.apache.org/rat/
2. A jar will be built called apache-rat/target/apache-rat-0.7-SNAPSHOT.jar
3. The generated packages should be unpacked into their own directories and have the following run against them, where RATPATH is the location of the RAT jar file:\\ java -jar $RATPATH/apache-rat-0.7-SNAPSHOT.jar <directory> > file.txt
4. <directory> should be replaced by the directory name for the archive scanned. file.txt should be replaced as instructed in the table below.

For example:

1. Change directory to the directory containing the release packages:
   cd release/
2. mkdir bin; cd bin; tar xzf ../apache-kato-M2-incubating-bin.tar.gz; cd..
3. java -jar $RATPATH/apache-rat-0.7-SNAPSHOT.jar bin/kato-M1-incubating >rat-bin.txt
4. Delete the directory:
   rm -rf bin

Uploading

1. The files should then be uploaded onto people.apache.org under a directory such as public_html/kato/M2-incubating. The files would be visible under http://people.apache.org/~userid/kato/M2-incubating (userid being the userid).
2. Call a vote for a release on the kato-dev@incubator.apache.org mailing list, at least 72 hours is needed before the results are announced. Three +1 votes are needed for a release to go ahead.
3. If approved, mail general@incubator.apache.org asking for the IPMC to vote on a release. For example: http://mail-archives.apache.org/mod_mbox/incubator-general/200910.mbox/browser
4. If approved, create a tag of the branch. :
   svn copy -m "Tag M2-incubating" https://svn.apache.org/repos/asf/incubator/kato/branches/M2-incubating https://svn.apache.org/repos/asf/incubator/kato/tags/M2-incubating
5. Upload the files from the previously created release/ directory. It is important that the files that were uploaded are the files that were voted on, with no changes. They should be copied to /www/www.apache.org/dist/incubator/kato/M2-incubating as they will then be mirrored.
6. After some time the files will be available under http://www.apache.org/dist/incubator/kato/M2-incubating. Update this page http://cwiki.apache.org/KATO/downloads.html.
   Update the "Recent Activity" section to mention the new release on the main wiki page.
7. Announce the successful release to kato-dev@incubator.apache.org and kato-spec@incubator.apache.org .
8. Any changes made for the release have to merged back into trunk. See here for details on merging. Normally the following would be done:
   First, find the revision numbers for the start and end of the release's branch by running svn --stop-on-copy log in the checked out directory or against the URL of the branch.
   With the trunk checked out, the merge can be performed by running svn merge -r 123:456 https://svn.apache.org/repos/asf/incubator/kato/branches/M2-incubating where 123 is the revision the branch was created and 456 is the revision of the last change.
   Run svn status to check on the status of the merge. Some files might need to be merged manually.
   Check in the merge with svn commit -m "Merge changes from M2-incubator branch"