This page is a guide, to making a release for the BookKeeper project. It's based off the Whirr instructions and our experience releasing.

First time

There are a few things which you need to set up before making a release.

PGP keys

You should have a 4096 bit RSA PGP key for signing the release. This key should be in the Apache web of trust. Once generated, ensure your key is in https://svn.apache.org/repos/asf/bookkeeper/dist/KEYS.

Maven setup

Put the following in ~/.m2/settings.xml. This will allow you to release and deploy to the apache maven repositories. Of course, it's best not to store your password in cleartext. See http://maven.apache.org/guides/mini/guide-encryption.html for a guide on how to make this a little more secure.

<settings>
<servers>
<server>
     <id>apache.snapshots.https</id>
     <username>APACHE-ID</username>
     <password>APACHE-PASSWORD</password>
   </server>
   <server>
     <id>apache.staging.https</id>
     <username>APACHE-ID</username>
     <password>APACHE-PASSWORD</password>
   </server>
   <server>
     <id>apache.releases.https</id>
     <username>APACHE-ID</username>
     <password>APACHE-PASSWORD</password>
   </server>
</servers>
</settings>

SSH setup on people.apache.org

The release procedure will require multiple logins to people.apache.org. To avoid having to log in many times, ensure that you have ssh password less login set up for people.apache.org.

http://www.thegeekstuff.com/2008/11/3-steps-to-perform-ssh-login-without-password-using-ssh-keygen-ssh-copy-id/

Making the release

The steps for releasing are as follows.

Create release branch
Generate release notes
Build and stage artifacts
Inspect the artifacts
Tag the release in Subversion
Run the vote
If vote gets +1 from 3 PMC members and no -1, go to next step, otherwise fix problem and repeat from step 2.
Release artifacts
Wait 24 hours for mirrors to sync
Update the website
Announce the release

Creating the release series branch (NEEDS UPDATE)

This only needs to be done for the first release of a series, (e.g. It needs to be done for 4.1.0 but not for 4.1.1 or 4.1.2).

Update CHANGES.txt, renaming the trunk section to reflect the version being released.

Create a branch for the release:

svn copy https://svn.apache.org/repos/asf/zookeeper/bookkeeper/trunk \
    https://svn.apache.org/repos/asf/zookeeper/bookkeeper/branches/branch-X.Y -m "Branching for X.Y releases"

Check out the new branch.

Update the version in all pom files. X.Y.0-SNAPSHOT -> X.Y.0
Commit these changes.

On trunk

Add a new trunk section in CHANGES.txt
Bump the version in all poms, X.Y.0-SNAPSHOT -> X.(Y+1).0-SNAPSHOT

Generate release notes

Generate the release notes from JIRA. https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311293

Select the correct version, in HTML format. Make it look like previous release notes. https://svn.apache.org/repos/asf/bookkeeper/site/content/docs/r4.1.0/releaseNotes.textile

Generate a list of all issues committed since last release. In this example, the last release was release-4.2.3, so we want to see all changes since that tag.

bookkeeper$ git log release-4.2.3..HEAD

Manually check that the list from JIRA, GIT and CHANGES.txt all reflect the same changes.

Update CHANGES.txt using the JIRA release notes in text format.

Build the artifacts

Make sure the branch builds cleanly. Check for errors and warnings in the output.

mvn clean findbugs:findbugs apache-rat:check install

Then build the artifacts.

mvn clean package assembly:single -DskipTests

This will generate

bookkeeper/target/bookkeeper-<VERSION>-src.tar.gz
bookkeeper-server/target/bookkeeper-server-<VERSION>-bin.tar.gz
hedwig-server/target/hedwig-server-<VERSION>-bin.tar.gz

Inspect the artifacts

Extract each of the generated artifacts;

Check file permissions are correct for all files
Check the LICENSE and NOTICE files cover all included jars (especially for the -bin packages)
Check the source package builds, and all tests pass
Check that "mvn apache-rat:check" passes on the source package.
Check that a bookie can be run from the source package and from the bookkeeper-server binary package
Check that a hedwig hub can be run from the source package and from the hedwig-server binary package

Staging the artifacts

Create a directory and copy the three tar.gz packages into it. Sign and generate md5 & sha1 hashes for each package.

md5sum <FILE>.tar.gz > <FILE>.tar.gz.md5
shasum <FILE>.tar.gz > <FILE>.tar.gz.sha1
gpg --armor -u yourname@apache.org --output <FILE>.tar.gz.asc --detach-sig <FILE>.tar.gz

Add these files to a directory in https://dist.apache.org/repos/dist/dev/bookkeeper (this is a subversion repo), naming it bookkeeper-<VERSION>-candidate-0.

... and into Maven

mvn clean deploy -Pdeploy

This will ask for your gpg passphrase.

Login to https://repository.apache.org using your Apache SVN credentials. Click on Staging on the left. Then click on org.apache.bookkeeper in the list of repositories. In the panel below you should see an open repository that is linked to your username and IP. Select this repository and click Close. This will close the repository from future deployments and make it available for others to view.

Tag the release

Commit changes to git, tag, and push:

git tag -u <your-gpg-key> release-4.2.4 -m "BookKeeper Release 4.2.4"
git push origin release-4.2.4

Run the vote

Send a mail like the following, updating the relevant content.

To: dev@bookkeeper.apache.org
Subject: [VOTE] BookKeeper X.Y.Z Release Candidate 0

This is the first release candidate for Apache BookKeeper, version X.Y.Z.

It fixes the following issues:
https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12319145&styleName=Html&projectId=12311293

*** Please download, test and vote by June 5th 2012, 10:00 GMT.

Note that we are voting upon the source (tag), binaries are provided for
convenience.

Source and binary files:
https://dist.apache.org/repos/dist/dev/bookkeeper/bookkeeper-X.Y.Z-candidate-0/

Maven staging repo:
https://repository.apache.org/content/repositories/orgapachebookkeeper-169/

The tag to be voted upon:
release-X.Y.Z (21f4a4cffefaa9391b79d79a7849da9c539af834)

BookKeeper's KEYS file containing PGP keys we use to sign the release:
https://dist.apache.org/repos/dist/release/bookkeeper/KEYS

Please download the the source package, and follow the README to build
and run a bookkeeper and hedwig service.

Release the artifacts

Move the release candidate into the release directory in subversion, stripping the candidate part from its name.

svn move https://dist.apache.org/repos/dist/dev/bookkeeper/bookkeeper-X.Y.Z-candidate-0 https://dist.apache.org/repos/dist/release/bookkeeper/bookkeeper-X.Y.Z

Remove the old releases from the release directory in subversion (we only need the latest release there, older releases are available through the archive):

svn rm https://dist.apache.org/repos/dist/dev/bookkeeper/bookkeeper-X.Y.Z

Release the repository in maven. Log in to https://repository.apache.org, click on Staging on the left. Select the repository that you closed earlier, and click Release, using a description like "Apache BookKeeper X.Y.Z artifacts". This will make the artifacts publicly available.

Update the website

See Building the website and documentation. Follow the pattern used for previous releases. Add the documentation for the release, the release notes, and link in the releases page and an update in the new page.

Announce the release (NEEDS UPDATE)

Assuming 24 hours have passed since releasing the artifacts, send a mail like the following.

To: bookkeeper-dev@zookeeper.apache.org, bookkeeper-user@zookeeper.apache.org, announce@apache.org
Subject: [ANNOUNCE] Apache BookKeeper 4.1.0 released

The Apache BookKeeper team is proud to announce Apache BookKeeper version
4.1.0.

This is the second release of the Apache BookKeeper subproject of ZooKeeper.
The BookKeeper project is made up of a distributed logging service called
BookKeeper and a distributed publish/subscribe system build on top of
BookKeeper called Hedwig.

For BookKeeper release details and downloads, visit:

http://zookeeper.apache.org/bookkeeper/releases.html

BookKeeper 4.1.0 Release Notes are at:
http://zookeeper.apache.org/bookkeeper/docs/r4.1.0/releaseNotes.html<http://zookeeper.apache.org/bookkeeper/docs/r4.0.0/releaseNotes.html>

We would like to thank the contributors that made the release possible.

Regards,

The BookKeeper Team

Child pages

Creating a release