Title: Release Guide

Apache ACE is an open source project, and as such its only official releases are source
releases. For convenience we also provide binaries. This document describes how to do a
source release. It is based on the [Release FAQ](http://www.apache.org/dev/release.html).

## Prerequisites

To create a release you *must*:

* Be a committer in the Apache ACE project;
* Have Ant installed on your system;
* Have Subversion installed on your system;
* Have gpg installed on your system;
* Have a public key added to the [keys file](http://www.apache.org/dist/ace/KEYS).

Before you can start staging a release candidate, you must:

* make sure there are no dependencies on snapshots/unreleased versions;
* double check that the version you want to create is correctly filled in in <tt>build/build.xml</tt>;
* create a tagged version of the sources in preparation of the release candidate.  

Creating a tagged version of the sources can be done directly through svn:

	:::sh
	$ svn copy https://svn.apache.org/repos/asf/ace/trunk/ https://svn.apache.org/repos/asf/ace/releases/X.Y.Z -m "Release X.Y.Z"

## Staging a release candidate

Staging a release starts by checking out a tagged version of the sources:

	:::sh
	$ svn co https://svn.apache.org/repos/asf/ace/releases/X.Y.Z ace-X.Y.Z

The next step is to build the software and create the archives:

	:::sh
	$ cd ace-X.Y.Z/build
	$ ant
	$ ant package

Then you sign archives by invoking the following target:

	:::sh
	$ ant sign

you can upload the archives and the signatures to our development area, which we use to
stage this release candidate. This development area can be found at
<tt>https://dist.apache.org/repos/dist/dev/ace</tt> and adding files to it can be done
using "svnpubsub" which is taken care of by the following target:

	:::sh
	$ ant commit-to-staging

## Voting on the release

Start a vote on the dev@ace.apache.org list, for example (be sure to replace
<tt>X.Y.Z</tt> with the *correct* version!):

	To: "Apache ACE developers list" <dev@ace.apache.org>
	Subject: [VOTE] Release ACE version X.Y.Z
	
	The source code of Apache ACE version X.Y.Z is available,
	along with an archive containing all dependencies and a
	binary release for convenience. They can all be found in
	our staging area here:
	https://dist.apache.org/repos/dist/dev/ace/

    You can use this UNIX script to download the release and
    verify the checksums and signatures:
    http://svn.apache.org/repos/asf/ace/trunk/etc/check_staged_ace.sh

    Usage:
    sh check_staged_ace.sh X.Y.Z
	
	Please vote to approve this release:
	[  ] +1 Approve the release
	[  ] -1 Veto the release (please motivate)
	
	This vote will be open for at least 72 hours.
	
The formal requirements on [approving a release](http://www.apache.org/dev/release.html#approving-a-release) are:

> Votes on whether a package is ready to be released use majority approval --
i.e. at least three PMC members must vote affirmatively for release, and there
must be more positive than negative votes. Releases may not be vetoed. Before
voting +1 PMC members are required to download the signed source code package,
compile it as provided, and test the resulting executable on their own
platform, along with also verifying that the package contains the required
contents.

The list of PMC (and project) members can be found [on this
page](http://ace.apache.org/get-involved/project-team.html).

Wrap up the vote with an e-mail to the <tt>dev@ace.apache.org</tt> list again:

	To: "Apache ACE developers list" <dev@ace.apache.org>
	Subject: [RESULT] [VOTE] Release ACE version X.Y.Z

	The vote has passed/failed with the following result:
	+1 (binding): ...
	+1 (non-binding): ...
	-1: ...

And, depending on the result, continue with either promoting or cancelling the release
below.

## Promoting the release

Move the artifacts from the development area to the final release location at
<tt>https://dist.apache.org/repos/dist/release/ace</tt> by invoking the following target:

	:::sh
	$ ant promote-to-release

Now wait at least 24 hours to allow the release to be properly mirrored and then update
the news and download page on the Apache ACE website and announce the release:

	To: "Apache ACE users list" <users@ace.apache.org>
	Subject: [ANN] ACE version X.Y.Z released.

	The Apache ACE team is proud to announce the release of ACE version X.Y.Z.
	
	This release is available from our download page at:
	http://ace.apache.org/downloads.html

After announcing the release, please update the baseline bundles contained in
trunk/cnf/releaserepo based on the released artifacts (remove old versions, keep only the
latest one).

Please also make sure that old releases are removed from
https://dist.apache.org/repos/dist/release/ace (the ant task does not do that yet).  Leave
the KEYS file in place. Take a look at http://www.apache.org/dev/release.html#when-to-archive
for more information about this.

## Cancelling the release

Remove the artifacts from the development area:

	:::sh
	$ ant delete-from-staging

We keep the tag in subversion for reference.