Title: Creating Releases
This is a how to document for creating Apache Jackrabbit releases. It
documents the current release process and needs to be updated as we move
forward.

<a name="CreatingReleases-Releaseplanning"></a>
## Release planning

Jackrabbit releases are created based on user demand and the availability
of fixes and other requested changes. Any committer can declare their plan
to cut a release by sending a "Apache Jackrabbit x.y.z release plan"
message to the dev@ list. The plan should refer to Jira for the list of
fixes to be included in the release and give a rough estimate of the
release schedule. It's OK to revise the plan if needed.

If you're not a committer, you can send a message to the mailing list
asking for a new release to be made. Including the list of specific fixes
you need and a short rationale of why you need the release.

<a name="CreatingReleases-Prerequisitesforreleasemanagers"></a>
## Prerequisites for release managers

You need to be a Jackrabbit committer to prepare and perform a release, but
anyone is welcome to help test the release candidates and comment on the
release plans.

You should have a code signing key that is included in the Jackrabbit KEYS
file. See Appendix A at the end of this page for more details.

You also need to tell Maven your Subversion credentials needed for
deploying artifacts to the Nexus server at https://repository.apache.org/.
See Appendix B for the required settings.

<a name="CreatingReleases-Releasemanagementtasks"></a>
## Release management tasks

1. Make sure that an appropriate version for the release is entered in Jira
and that all the related issues have been resolved.
* Create a *RELEASE-NOTES.txt* file in the root folder of the project to
be released. If such a file already exists, update it for the release. When
done, commit the file. See previous release notes for examples of what to
include. The release note report in Jira is a useful source of required
information.
1. Build and deploy the release artifacts with Maven. See below for the
exact steps.
1. Close the staged repository on repository.apache.org.
1. Start the vote thread, wait 72 hours. See the vote template generated by
the Maven build.
1. If the vote fails (easy case first) remove the tag from svn and drop the
staged repository - done
1. If the vote is successful, copy the release archives to the dist
directory on www.apache.org, delete the old release there (its
automatically archived), and promote the staged repository for
synchronization to Maven central.
1. Update the Jackrabbit web site to point to the new release.
1. Send the release announcement once the web site and download mirrors have
been synced.
1. Mark the version as released in Jira and close all related issues.

<a name="CreatingReleases-Stepstobuildthereleaseartifacts"></a>
## Steps to build the release artifacts

The release is built using the Maven release plugin. See the [Releasing a Maven project](http://maven.apache.org/developers/release/releasing.html)
 guide for more details.

1. Execute *mvn release:prepare*. This will update the POM files and tag
the release in svn.
1. Execute *mvn release:perform*. This will build the tagged release and
deploy the artifacts to a staging repository on repository.apache.org. The
non-Maven release artifacts are automatically deployed to your home
directory on people.apache.org.

<a name="CreatingReleases-RelatedLinks"></a>
## Related Links

* http://www.apache.org/dev/release.html
* http://www.apache.org/dev/release-signing.html
* http://wiki.apache.org/incubator/SigningReleases
* http://www.apache.org/dev/repository-faq.html

<a name="CreatingReleases-AppendixA:CreateandaddyourkeytotheJackrabbitKEYSfile"></a>
## Appendix A: Create and add your key to the Jackrabbit KEYS file

Follow these instructions to generate your code signing key and to add it
to the Jackrabbit KEYS file.

1. [Generate a code signing key](http://www.apache.org/dev/release-signing.html#generate)
 using your @apache.org address as the email and "CODE SIGNING KEY" as the
comment.
1. The Jackrabbit KEYS file is managed in
https://svn.apache.org/repos/asf/jackrabbit/dist/KEYS. To modify the file,
first checkout the dist directory:
{code:none}
svn checkout https://svn.apache.org/repos/asf/jackrabbit/dist

    # See the beginning of the KEYS file for instructions on how to append your
key to the file.
    # Once you've committed the changes, update the KEYS file on
{{people.apache.org}}:
    {code:none}
    umask 002; svn update /www/www.apache.org/dist/jackrabbit

1. You are *DONE*, but to see the changes on
http://www.apache.org/dist/jackrabbit/KEYS you must wait 2 hours

You should get your key [linked to the Apache web of trust](http://www.apache.org/dev/release-signing.html#apache-wot)
. Once other people have signed your key, you can update the KEYS file with
the signatures you've received.

<a name="CreatingReleases-AppendixB:Mavensettings"></a>
## Appendix B: Maven settings


    <settings>
    ...
      <servers>
        <!-- To deploy a Jackrabbit snapshot -->
        <server>
          <id>apache.snapshots.https</id>
          <username> <!-- YOUR APACHE SVN USERNAME --> </username>
          <password> <!-- YOUR APACHE SVN PASSWORD --> </password>
        </server>
        <!-- To stage a Jackrabbit release -->
        <server>
          <id>apache.releases.https</id>
          <username> <!-- YOUR APACHE SVN USERNAME --> </username>
          <password> <!-- YOUR APACHE SVN PASSWORD --> </password>
        </server>
        ...
      </servers>
    </settings>