Setting up the signing keys

Before you do a release you'll need a signing key that is registered with apache. If you already have one, you can skip this section. Otherwise, here are the steps to do:

1. use gpg2 --gen-key to generate a new key. Make sure that the key size is 4096 bits, the key doesn't expire, and use CODE SIGNING KEY for the comment.
2. Now you need to register your key at http://pgp.mit.edu/ using the output of gpg --armor --export <keyid>
3. Add your key to the KEYS file:
   1. svn co https://dist.apache.org/repos/dist/release/zookeeper/ zookeeper_dist
   2. cd zookeeper_dist.
   3. edit the KEYS file. See the top of the KEYS file for instructions on how to edit this file
   4. svn ci
4. Upload digest to your account on id.apache.org (gpg2 --fingerprint)

Useful Links and Background:

Apache infra page: https://cwiki.apache.org//confluence/display/INFRA/Index

Apache self-service page - now allows for forcing git repo sync: https://selfserve.apache.org/

Important Notes

• when updating JIRA be sure to use the "batch change" operator under the "tools" menu. Disable email notifications when using batch change, subsequent to large JIRA operations (moving issues btw releases, closing JIRAs after a release, etc...) send email to the dev@ list detailing the changes.

Configuring maven

Make sure your settings.xml in ~/.m2 contain logins for apache repos, and your signing key is published and configured here.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <servers>
    <!-- To publish a snapshot -->
    <server>
      <id>apache.snapshots.https</id>
      <username>YOUR_APACHE_ID</username>
      <password>YOUR_APACHE_PASSWORD</password>
    </server>

    <!-- To stage a release -->
    <server>
      <id>apache.staging.https</id>
      <username>YOUR_APACHE_ID</username>
      <password>YOUR_APACHE_PASSWORD</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>apache-release</id>
      <properties>
	    <!-- gpg --list-keys will show you your keyname ( something like 00A5F21E) -->
    	<gpg.keyname>YOUR_KEYNAME</gpg.keyname>
  		<gpg.passphrase>YOUR_KEY_PASSWORD</gpg.passphrase>
      </properties>
    </profile>
  </profiles>
</settings>

For a more detailed steps, check out How To Release page for Hadoop. It is used as a base.

Smoke Tests

Before the release, run the following smoke tests (at least).

• Run unit tests on different hardwares: mac, windows, linux.

Branching and Tagging

• Check out the branch you are making the release of:

  git clone -b branch-X.Y https://gitbox.apache.org/repos/asf/zookeeper.git

• If you are creating a point release (almost always the case) then follow this step. The exception to this is typically only when creating a new release candidate because the previous candidate failed during voting (rc0 failed and you are creating rc1+) – in which case skip this step.
  
  

  Create a branch for X.Y.Z (the current release candidate)
  

  git branch branch-X.Y.Z
  git push <remote> branch-X.Y.Z

• Update to next SNAPSHOT version

  mvn clean org.codehaus.mojo:versions-maven-plugin:2.7:set -DgenerateBackupPoms=false -DnewVersion=X.Y.(Z+1)-SNAPSHOT

  
  Also update the version number in zookeeper-client/zookeeper-client-c/configure.ac, zookeeper-client/zookeeper-client-c/CMakeLists.txt, and zookeeper-client/zookeeper-client-c/include/zookeeper_version.h to the next logical SNAPSHOT version (e.g. X.Y.Z to X.Y.(Z+1)-SNAPSHOT)
  
  

• Do a search in the project for the version with the attached -SNAPSHOT to make sure it is changed everywhere. Some files (other than pom.xml) might also contain a hard coded version.
  

• Commit these changes.

  # check for modified files
  git status
  
  # add modified files one by one
  git add <modified files>
  
  # commit and push the changes to remote repo branch-X.Y
  git commit -m "Prepare for the next release: update the version to X.Y.(Z+1)-SNAPSHOT"
  git push <remote> branch-X.Y

• Checkout the active point release branch - this is where you will be creating the release candidate
  
  

  git checkout branch-X.Y.Z

• If not already done, cherry-pick desired commits into branch-X.Y.Z. If cherry-picks are done from other than branch-X.Y ensure that those changes are also committed to branch-X.Y. If there are conflicts, then it is preferable to produce a new patch for this branch, review it separately and commit it via JIRA. Please refer HowToContribute and Committing changes page for pushing changes to the project. 
  
  

  # The -x option records the source commit, and reuses the original commit message
  git cherry-pick -x <commit-hash>

• Update zookeeper-docs/src/main/resources/markdown/releasenotes.md with release notes for this release. You can get the HTML by following the "Release Notes" link for the relevant release on the https://issues.apache.org/jira/browse/ZOOKEEPER?report=com.sourcelabs.jira.plugin.portlet.releases:releases-projecttab#selectedTab=com.atlassian.jira.plugin.system.project%3Aroadmap-panel tab in Jira. Note that you need to exclude the won't fix or invalid tickets.

• Update versions in pom.xml (remove SNAPSHOT):

  mvn clean org.codehaus.mojo:versions-maven-plugin:2.7:set -DgenerateBackupPoms=false -DnewVersion=X>Y>Z

  Make sure the version number is correct in zookeeper-client/zookeeper-client-c/configure.ac, zookeeper-client/zookeeper-client-c/CMakeLists.txt, and zookeeper-client/zookeeper-client-c/include/zookeeper_version.h 

• Update the version number in build.xml to be ''X.Y.Z'' (i.e. remove SNAPSHOT designator)
• Update the copyright years in NOTICE.txt if it's outdated.

• Commit these changes.
  

  # check for modified files
  git status
   
  # add modified files one by one
  git add <modified files>
    
  # commit and push the changes to remote repo branch-X.Y
  git commit -m "Preparing for release X.Y.Z"
  git push <remote> branch-X.Y.Z

• Tag the release candidate (R is the release candidate number, and starts from 0):

  # create a signed tag
  git tag -s release-X.Y.Z-rcR -m "ZooKeeper X.Y.Z-rcR release."
   
  # push the newly created rc tag to the remote repo.
  git push <remote> release-X.Y.Z-rcR

Building

• Build the projects with maven (we are skipping runit the unit tests here, but you should run them at least once on the release branch before continuing)

  mvn clean install -DskipTests
  

• You should have the jar files and also the tarballs built. The two tarball is available at: //TODO: sign ZK jars in bin-package?
  • zookeeper-assembly/target/zookeeper-X.Y.Z-bin-package.tar.gz
  • zookeeper-assembly/target/zookeeper-X.Y.Z-source-package.tar.gz

Publishing

Once three PMC members have voted for a release, it may be published.

• Deploy to the Maven Repository.
  This is done using apache-release profile, coming from the apache parent pom. This will also sign your artifacts if your settings.xml is configured as mentioned above.
  The following command copies all artifacts to a temporary staging Apache mvn repository in open state:
  

  mvn deploy -DskipTests -Papache-release
  

• Make the release candidate available
  

  You can check the artifacts you just uploaded in the Apache’s Nexus at repository.apache.org using your Apache ID. Click 'Staging Repositories' and look for a new ZooKeeper repository with a status of 'Open'. Check that all the artifacts and pom files are available. As long as this is in open state, you can re-upload your files. Or just use 'Drop' on the staging repo.

  If it checks out, close the repo using the 'Close' button. The repository must be closed before a public URL to it becomes available. It may take a few minutes for the repository to close. Once complete you’ll see a public URL to the repository in the Nexus UI. You may also receive an email with the URL. Provide the URL to the temporary staging repository in the email that announces the release candidate.

  When the release vote concludes successfully, return here and click the 'Release' button to release the artifacts to central. The release process will automatically drop and delete the staging repository.

• In Jira, close issues resolved in the release. Disable mail notifications for this bulk change.