========================
Jackrabbit Release Guide
========================

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.

See also http://www.apache.org/dev/release.html for more general Apache
release documentation.

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. See the list archive for example plans.

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.

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. The Jackrabbit committer that volunteers as a release
manager needs to prepare by completing the following one-off tasks:

  1) You should have a code signing key that is included in the Jackrabbit
     KEYS file in https://dist.apache.org/repos/dist/release/jackrabbit/KEYS.
     If you don't have one yet, first read the release signing documentation
     at http://www.apache.org/dev/release-signing.html and then complete the
     following steps:

     * Generate a code signing key using your @apache.org address as the
       email and "CODE SIGNING KEY" as the comment. Instructions are in
       http://www.apache.org/dev/release-signing.html#generate

     * Checkout the KEYS file from the release repository:

       $ svn checkout --depth files \
             https://dist.apache.org/repos/dist/release/jackrabbit \
             jackrabbit-release

     * See the beginning of the KEYS file for instructions on how to
       append your key to the file. Once you've done that, you can commit
       the updated file. The changes should become visible in
       http://www.apache.org/dist/jackrabbit/ within a few moments.

     * If possible, you should get your key linked to the Apache Web of Trust,
       described in 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.

     * It's also a good idea to upload your key to a public key server like
       the one in http://pgpkeys.mit.edu/.

  2) You should adjust your Maven settings to in preparation for staging and
     publishing release artifacts. Start by reading the general documentation
     in http://www.apache.org/dev/publishing-maven-artifacts.html. Then
     configure your environment as outlined in
     http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env.

Release management tasks
------------------------

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.

Build and deploy the release artifacts as outlined below:

  * Execute mvn release:prepare. This will update the POM files and tag
    the release in svn.

  * Execute mvn release:perform. This will checkout and build the tagged
    release, and deploy the artifacts to a staging repository on
    https://repository.apache.org/. The non-Maven release artifacts are
    automatically packaged under target/checkout/target.

Close the staged repository on repository.apache.org.

Upload the artifacts to https://dist.apache.org/repos/dist/dev/jackrabbit/
(instructions at the end of the build)

  cd /path/to/jackrabbit-dev
  scp -r /path/to/jackrabbit/target/checkout/target/$version $version
  svn add $version
  svn commit -m "Apache Jackrabbit $version release candidate" $version
  
Start the vote thread, wait 72 hours. See the vote template generated
by the Maven build.

If the vote fails (easy case first) remove the tag from svn and drop the
staged repository - done

If the vote is successful

  * close the vote by publishing the results

  * copy the release candidate from dev/jackrabbit to release/jackrabbit
    in https://dist.apche.org/repos/dist/, and delete any older releases
    from the same branch (they're automatically archived),

    svn move -m "Apache Jackrabbit $version" \
        https://dist.apache.org/repos/dist/dev/jackrabbit/$version \
        https://dist.apache.org/repos/dist/release/jackrabbit/$version

  * release the staged repository for synchronization to Maven central.

  * mark the version as released in Jira

  * close all the issues included in the release

  * Update the Jackrabbit web site to point to the new release.

  * Send the release announcement once the web site and download mirrors
    have been synced.