#Releasing TomEE

	This document is aimed at guiding a release manager through the general release process. You will need either a Linux, Mac, or failing that a Linux Virtual (with at least a 50GB Drive) on Win. 

###Preparation of The Branch
	
Run **ant -f rat.xml > report.txt** on trunk to ensure all licences are in place.

 - Review the report.txt and update/add missing headers until clean.
 - *Tip*, search for **Unapproved licenses:** at the beginning of the report for a list.

Branch the version to release and ensure it builds and passes all tests.

Add a buildbot CI setup for branch here:

[https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/tomee.conf](https://svn.apache.org/repos/infra/infrastructure/buildbot/aegis/buildmaster/master1/projects/tomee.conf)

Basically search for the following line and it should be obvious how to add a new builder:

	c['builders'].append(tomee_hemera_builder("tomee-trunk-ubuntu", "tomee/tomee/trunk"))
	
An SVN trigger must be added afterwards. This can only be done by someone with admin permissions, such as any PMC chair or an Infra team member.
Just drop an email to *infrastructure@apache.org*

###Create a TCK Branch

Branch the TCK using the same version as the release branch from here:

[https://svn.apache.org/repos/tck/tomee-tck/trunk](https://svn.apache.org/repos/tck/tomee-tck/trunk)

Update the TCK branch files to point to the version branch.

	\tckbranch\plus.properties
	\tckbranch\pom.xml
	\tckbranch\webprofile-plus.properties
	\tckbranch\webprofile.properties

Run **ant -f rat.xml > report.txt** on the branch.

 - Review the report.txt and update/add missing headers until clean.
 - *Tip*, search for **Unapproved licenses:**.

###Check SVN Authentication
 
Pre-authenticate svn repositories to ensure your credentials are cached before using any tools.

	svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://svn.apache.org/repos/asf/tomee/tomee/branches/testdir1
	svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://svn.apache.org/repos/asf/tomee/tomee/branches/testdir1
	svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://repository.apache.org/content/repositories/testdir2
	svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://repository.apache.org/content/repositories/testdir2
	svn mkdir --username [apacheuser] --password [apachepw] -m "Create test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3
	svn delete --username [apacheuser] --password [apachepw] -m "Delete test dir" https://dist.apache.org/repos/dist/dev/tomee/testdir3

###Prepare Maven Authentication

Ensure your maven .m2/settings.xml correct, and be aware that the tools currently require a clear text password:

	<server>
	  <id>apache.snapshots.https</id>
	  <username>un</username>
	  <password>pw.in.clear</password>
	</server>

	<server>
	  <id>apache.releases.https</id>
	  <username>un</username>
	  <password>pw.in.clear</password>
	</server>

	<server>
	  <id>apache.dist.https</id>
	  <username>un</username>
	  <password>pw.in.clear</password>
	</server>

	<profiles>
		<profile>
		...
			<repositories>
				<repository>
				  <id>apache.dist.https</id>
				  <url>https://dist.apache.org/repos/dist</url>
				</repository>
			  </repositories>

###Code Signing Setup

If this is your first release then you will have to ensure that you have a code signing key prepared on the machine from which you perform the release. The process is quite intense. You can find information here:

 - [http://www.apache.org/dev/release-signing.html](http://www.apache.org/dev/release-signing.html)
 - [http://maven.apache.org/developers/release/pmc-gpg-keys.html](http://maven.apache.org/developers/release/pmc-gpg-keys.html)
 
However, the basic steps are:

 - Create a key using **gpg --gen-key**, using size 4096 and answering the questions that command issues.
 - During the process you will have to generate random entropy, this is best achieved in another console and issuing the command **find / > /dev/null** and waiting a minute.
 - List the keys using **gpg --list-keys** and take note of the name

Once you have your key then you will need to append it to the key file here:

 - [http://www.apache.org/dist/tomee/KEYS](http://www.apache.org/dist/tomee/KEYS)

That is best done as the file itself explains, once you open and view it in a UTF-8 safe text editor you will see the description at the top.  
Just follow the instructions there on how to append your key. The basic steps are also here, please read both before you proceed:

 - Save the KEYS file on your local machine and import it using **gpg --import KEYS**
 - Then create the new KEYS file using **(gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS**
 - Check that the new KEYS file contains your key.
 - Log in to people.apache.org and locate /dist/tomee/KEYS
 - Make a backup of the remote KEYS file just in case
 - Overwrite the old /dist/tomee/KEYS file with your new one that now also contains your key.
 - Go to [http://pgp.mit.edu/](http://pgp.mit.edu/) and add your ascii armoured key
 - Take note of your key fingerprint using **gpg --fingerprint <your name>**
 - Go to [https://id.apache.org](https://id.apache.org), log in and fill OpenPGP Public Key Primary Fingerprint: with the value of your fingerprint.
 
###Build the Release Tools

Checkout the release tools using SVN from here [https://svn.apache.org/repos/asf/tomee/sandbox/release-tools](https://svn.apache.org/repos/asf/tomee/sandbox/release-tools)

Really read the README.mdtext and follow the instructions for building the 3rd party libraries.  
Basically SVN checkout and compile [Swizzle](https://svn.codehaus.org/swizzle/trunk) and [Tentacles](https://svn.apache.org/repos/asf/creadur/tentacles/trunk)

Build the release tools, *mvn clean install -DskipTests -DfailIfNoTests=false*

Have a look at **run.sh** to see the entry point.

Understand that the release tools are not polished, and you currently may have to edit source and re-compile.

###Site Staging
<a href="#staging"/>
For some of the release steps you will need to provide documentation on the site. Checkout the site here:

[https://svn.apache.org/repos/asf/tomee/site/trunk](https://svn.apache.org/repos/asf/tomee/site/trunk)

Most of the content can be found under 'content' and subdirectories.

When you commit changes the site should be built automatically by the buildbot, but you can force a build on IRC using:

    **tomee-bot: force build tomee-site-staging**

The buildbot staging result can be seen here:

[http://ci.apache.org/builders/tomee-site-staging](http://ci.apache.org/builders/tomee-site-staging)

And the actual staging site, where you can review your changes, is here:

[http://tomee.staging.apache.org/](http://tomee.staging.apache.org/)

Once you are happy with the staging you can publish to the real site using:

[https://cms.apache.org/tomee/publish](https://cms.apache.org/tomee/publish)

###Begin The Release Process

Ensure TCK is passing all tests, and if so create an SVN tag from the branch.

	Note: It is a future goal to either separate OpenEJB from TomEE or unify the versions so the
	[maven-release-plugin](http://maven.apache.org/maven-release/maven-release-plugin/) can be used.

	Because we cannot use the Maven release tools we currently have to create a an SVN tag manually. The best way to do this is to:
	
	 - Copy the branch to a staging branch using:  
	   > svn copy https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]  https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging -m "Staging [version]"
	 - Checkout the staging branch using:  
	   > svn co https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging tomee-[version]-staging
	 - Update all SNAPSHOT versions to the release versions in the local tomee-[version]-staging and commit.
	 - Create the tag from the staging:  
	   > svn copy https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging https://svn.apache.org/repos/asf/tomee/tomee/tags/tomee-[version] -m "Tag [version]"
	 - Delete the staging branch using:  
	   > svn rm https://svn.apache.org/repos/asf/tomee/tomee/branches/tomee-[version]-staging -m "Delete staging"

Open a console on the release-tools directory.

Note: Before running any **./run.sh** activity always check the release tools code for the command tomee-release-tools/src/main/java/org/apache/openejb/tools/release/cmd.
At the moment some of the commands need manually editing to work. Eventually the commands should be re-written.

All JIRA actions should be performed on the ASF JIRA here:

[https://issues.apache.org/jira/browse/TOMEE](https://issues.apache.org/jira/browse/TOMEE)

Ensure JIRAs have been filed for commits using **./run.sh reviewcommits**

Update fixVersions for JIRAs used in SVN commits using **./run.sh updatejiras** - *Untested, requires investigation*

Review and bulk Close all JIRAs for the version to be released.

Publish the changed binaries report (if any) using **./run.sh comparelibraries**

Write and publish the release notes preview on the staging site. 

Publish a summary of the RAT report preview on the staging site.

Using the RAT report as a guide update LICENSE and NOTICE files for any changed binaries, and add new ones if required.

Update branch versions. How you do this is up to you at this point in time.

Update trunk versions. How you do this is up to you at this point in time.

Create the next version iterations in JIRA.

###Rolling Out The Preview

	Note: Before running anything below ensure you either have:

	 - A valid tomee-release.properties from the last release in your home directory (Speak to the last release manager).
	 - Or have modified **tomee-release-tools/src/main/java/org/apache/openejb/tools/release/Release.java** with current versions and **mvn clean install**.
	 	 
Ensure the TCK passes with preview repositories by editing and ensuring paths are correct in the following files:

	\tckbranch\plus.properties
	\tckbranch\pom.xml
	\tckbranch\webprofile-plus.properties
	\tckbranch\webprofile.properties

Publish the preview using **./run.sh roll binaries legal releasenotes preview** - You can run these tasks like so, or individually in order.
It will be likely that this will have to be repeated several times before a successful vote.

The *legal* step will create the legal report files in the /tmp/download/staging-[revision]/legal directory. These need to be added to the staging repo.
 - Delete the [legal]/repo and [legal]/content directories, as these are no longer required
    rm -R /tmp/download/staging-[revision]/legal/content
    rm -R /tmp/download/staging-[revision]/legal/repo

 - Perform a non-recursive checkout of the staging repo and add the legal:
	svn co -N https://dist.apache.org/repos/dist/dev/tomee/staging-[revision] /tmp/download/staging
	mv /tmp/download/staging-[revision]/legal /tmp/download/staging
	cd /tmp/download/staging-[revision]
	svn add legal

Once the binaries are in place add the staging repository to the corresponding TCK project and fire off a build.
To fire off a build on EC2 from the TCK directory speak to the last release manager for the **curl** command to use

If the TCK fails then discuss, fix and re-roll.

Publish a [Vote](https://www.apache.org/foundation/voting.html) if, and only if, the TCK passes.

Votes are generally managed and identified using keywords such as [VOTE], [CANCELLED] and [RESULT]

If the vote fails then discuss, fix and re-roll.

###Voted Binaries

Once the vote has passed then release the binaries on Nexus: [https://repository.apache.org/index.html#welcome](https://repository.apache.org/index.html#welcome)

Update both OpenEJB and TomEE JIRA versions as released (Set the release date).

Copy the binaries to the release location (User rights require a PMC to do this)

	From: https://dist.apache.org/repos/dist/dev/tomee/staging-[stagingId]/tomee-[version]
	To: https://dist.apache.org/repos/dist/release/tomee/tomee-[version] 
    

Wait for the binaries to replicate to mirrors. Here is a neat script from David to check the status:

    #!/bin/bash

    RELEASE=${1?Specify a release, such as './mirror_check.sh tomee-1.7.1'}

    function list_mirrors {
        DYN=http://www.apache.org/dyn/closer.cgi/tomee/$RELEASE/
        wget -q -O - $DYN | tr '">< ' '\n' | grep "^http.*$RELEASE/" | sort | uniq
    }

    function status_code {
        wget -v "$1" 2>&1| grep 'awaiting response' | tr ' ' '\n' | grep "[0-9]"
    }

    list_mirrors | while read n; do
        echo "$(status_code $n) $n"
    done | sort | grep 'http'

Commit and publish changes to the site, see [Site Staging](release-tomee.html#staging)

    https://cms.apache.org/tomee/publish


###Blog

Announce to the world that TomEE has new bells and whistles!

[https://blogs.apache.org/roller-ui/login.rol](https://blogs.apache.org/roller-ui/login.rol)  
[http://twitter.com/ApacheTomEE](http://twitter.com/ApacheTomEE)  
[http://facebook.com/ApacheTomEE](http://facebook.com/ApacheTomEE)  
[https://plus.google.com/118203123063829126066](https://plus.google.com/118203123063829126066)