Information/Recipes for Curator Committers

Tools/Preparation

• Tools
• GPG
• Maven Settings
• Git Setup
• SVN Setup

Development

• GitHub Flow
• GitHub Mirror and Pull Requests
• Travis-CI
• Jira
• Maven Checks
• Code Style
• Versioning

Releasing Curator

• Overview
  • Prepare the Release
  • Stage the Apache Release
  • Initiate a Vote On the Release
  • Promote the Release
  • Clean Up Old Releases
• How to Publish the Curator Website

Tools

Curator is built using Maven and Git. You should be familiar with both of these tools. For publishing, you also need to install GPG and create a key that is available from a well known public site.

GPG

Download GPG from http://www.gnupg.org/download/.

1. Generate PGP code signing keys
2. Ensure that your PGP signing keys are available in the KEYS file that is in the release directory (see SVN Setup).

If you are not already a member of the Web Of Trust (WOT) it would be a good idea to do so. You can read more about key signing here.

Ensure that you have setup your ssh keys on people.apache.org, otherwise you'll have to enter your login password a number of times (best use ssh-agent for this as well). A good overview of this process can be found here (ssh-copy-id and ssh-agent in particular).

NOTE: when doing a release you will be asked for your PGP password multiple times unless you set up the gpg-agent. Mac users have reported trouble getting gpg-agent to work. You can also set your gpg-password in the Maven settings file (see below).

Maven Settings

Your Maven settings (~/.m2/settings.xml) file should have the following (note: curator-website-checkout-path is used as a temporary path when deploying the Curator website):

<settings>
    ...
    <servers>
        ...
        <server>
            <id>apache.website.svnpub</id>
            <username>Your Apache Username</username>
            <privateKey>${user.home}/.ssh/id_rsa</privateKey>
        </server>
 
        <server>
            <id>apache.releases.https</id>
            <username>Your Apache Username</username>
            <password>APACHE-PASSWORD-ENCODED</password>
        </server>
 
        <server>
            <id>apache.snapshots.https</id>
            <username>Your Apache Username</username>
            <password>APACHE-PASSWORD-ENCODED</password>
        </server>
        ...
    </servers>

    <profiles>
        <profile>
            <properties>
                ...
    	        <gpg.keyname>id-of-your-pgp-key</gpg.keyname>
                <gpg.passphrase>your-pgp-password</gpg.passphrase> <!-- use this if pgp-agent doesn't work for you -->
                ...
            </properties>
            ...
        </profile>
        ...
    </profiles>
    ...
</settings>

Note: you can store encrypted passwords your settings.xml if you want. Read the details here: http://maven.apache.org/guides/mini/guide-encryption.html

Git Setup

Apache has a good guide on how to prepare your environment for interacting with the Curator Git repo: https://git-wip-us.apache.org/.

SVN Setup

While Curator mainly uses git for source control, certain components required by Apache use SVN. You should checkout the following SVN projects into unique local directories:

• Staging directory: svn co https://dist.apache.org/repos/dist/dev/curator/
• Release directory: svn co https://dist.apache.org/repos/dist/release/curator/

You must add your GPG key to the KEYS file in "repos/dist/release/curator/" and commit the changes. E.g. (replace NAME with the user name you used to generate the keys)

cd DIST RELEASE CURATOR directory
(gpg --list-sigs NAME && gpg --armor --export NAME) >> KEYS
svn commit -m "Added my keys"

Development

GitHub Flow

Curator loosely uses GitHub Flow. The short form:

• Anything in the master branch is deployable
• The upcoming release is always "master"
• To work on something new, create a descriptively named branch off of the upcoming release - usually the ID of the Jira issue (e.g. CURATOR-16)
  • Commit to that branch locally and regularly push your work to the same named branch on the server
  • When you need feedback or help or you think the branch is ready for merging, send an email on dev@curator.apache.org and ask for the branch to be reviewed
  • After someone else has reviewed and signed off on the feature, merge it into "master"

Code Style

Curator uses the very popular "JZ" style. For IntelliJ IDEA users, here's a code style file: JZ.xml

Versioning

Curator uses semantic versioning. The best description of this is from Curator committer Eric Tschetter:

Essentially, it tells you the API compatibility between multiple dependencies. For example,

If you have version 1.0.0 and 1.0.1, you can use either one and you will not run into errors due to API conflicts (i.e. in Java, no ClassNotFound or NoSuchMethod type exceptions)

If you have 1.0.0 and 1.1.0, you can replace 1.0.0 with 1.1.0 and you will not have errors due to API conflicts. If you try to swap 1.0.0 in place of something that depends on 1.1.0, however, you *might* have errors due to API conflicts. I.e. you can go forward without errors, but not backwards

If you have 1.0.0 and 2.0.0, you will likely have errors due to API conflicts if you replace either one with the other.

Make sure you choose an appropriate version for each release. The Maven build will output messages if there are API compatibility issues (look for the "clirr-maven-plugin" messages).

GitHub Mirror and Pull Requests

Curator's source is mirrored on GitHub at: https://github.com/apache/curator. Non-committers are asked to fork this repository and submit pull requests (PR) for changes. When a PR is received, a Curator committer can test and possibly merge it by:

• Create a branch for the PR: git checkout -b <branch name> - the branch name is usually the JIRA ID of the issue
• Pull the changes from the PR: git pull https://github.com/<users-name>/exhibitor.git <branch>
• Test, updated, etc. the change. Periodically push the change to the main repo. For the initial push: git push -u origin <branch name>
• If the change is accepted, merge it into the master branch and push the master branch. This will automatically close the GitHub PR. NOTE: Please use git merge --squash as this makes it easier to read the history and do cherry-picks.

Declining Pull Requests

If a Curator committer wants to close a PR without merging, it can be accomplished via:

• git commit --allow-empty -m "closes #NN *Reason PR is being declined*"
• git push

Travis-CI

There is a continuous integration job for Curator at

• https://travis-ci.org/apache/curator

Jira

For all but minor changes, there should be a Jira "ticket" created at https://issues.apache.org/jira/browse/CURATOR.

Maven Checks

Regardless of which IDE you use, you should periodically perform a mvn clean install to validate that the various configured checks (such as license headers, etc.) are passing as well as the unit tests.

Releasing Curator

To release Curator, the following steps must be followed:

1. The binary artifacts must be staged
2. The Apache release must be staged
3. The release must be voted on
4. If the vote succeeds:
   • The Apache release must be promoted
   • The binary artifacts must be released

Prepare the Release

1. Do a dry run of the release/prepare step by executing mvn -P apache-release release:prepare -DdryRun=true. The dry run will not commit any changes back to Git and gives you the opportunity to verify that the release process will complete as expected. If you need to cancel, execute mvn release:clean and then reset via git reset --hard.
2. Verify that the release process completed as expected:
   • The release plugin will create pom.xml.tag files which contain the changes that would have been committed to SVN. The only differences between pom.xml.tag and its corresponding pom.xml file should be the version number.
   • If other formatting changes have been made you should review the changes and then commit and push them.
   • Once any failures or required updates have been committed to svn, rollback the release prepare files: mvn release:rollback
3. Execute the release/prepare step for real this time
   • You'll be prompted for the same version information and optionally your GPG
     passphrase again
   • mvn -P apache-release release:prepare
   • mvn -P apache-release release:perform
   • git push --tags
4. Verify the staged artifacts in the Apache Nexus repository:
   • Go to: https://repository.apache.org/index.html
   • Login
   • Select Staging Repositories under the Build Promotion section on the left hand side
   • Select the repository from the main window
   • Select the content tab at the bottom of the screen and navigate through the artifact tree and double check things.
5. Close the Nexus staging repo by clicking on the curator repo and clicking the "Close" button.
6. IMPORTANT: Do NOT release the binaries yet

Stage the Apache Release

1. At the root of your Curator directory, find the target directory.
2.  In the directory you will now find 3 files that need to be staged:
   
   • apache-curator-X.X.X-source-release.zip
   • apache-curator-X.X.X-source-release.zip.asc
   • apache-curator-X.X.X-source-release.zip.sha512
3. These files must be put into the staging directory (svn co https://dist.apache.org/repos/dist/dev/curator/)
   • Create a directory for the release
   • cp the files to this directory
   • Remove any old release directories via: svn rm
   • Add the new directory via: svn add

   • Commit via: svn commit

Initiate a Vote On the Release

Create a VOTE email thread on dev@curator.apache.org to record votes as replies (see Example Emails).

• The release needs 3 +1 votes from the PMC
• If the Vote succeeds, you can promote the release
• Regardless of the vote result, send a RESULT VOTE email (see Example Emails).
• In the rare case that the release needs to be canceled:
  • Go to: https://repository.apache.org/index.html and "drop" the build.
  • Send a CANCEL VOTE email (see Example Emails).
  • If you need to delete the tag:
    git tag -d <tag>
git push origin :refs/tags/<tag>

Promote the Release

1. These files must be put into the release directory (svn co https://dist.apache.org/repos/dist/release/curator/)
   • Create a directory for the release
   • cp the files to this directory and then svn commit
2. Release the binary artifacts
   • Go to: https://repository.apache.org/index.html
   • Select the curator release and click the "Release" button.
3. Announce the release (see Example Emails) to these mailing lists. Remember to use your apache.org email address to send the email :
   • user@curator.apache.org
   • dev@curator.apache.org
   • announce@apache.org
   • user@zookeeper.apache.org
4. Update the Releases Wiki: https://cwiki.apache.org/confluence/display/CURATOR/Releases
   • Add the new release to the "All Releases" table
   • Make sure all links to downloads, release notes, etc. are "https"
   • The Curator Website MUST be re-published with the new release version (see Step 7)
5. You MUST publish the Curator Website (see below) prior to the next step
6. Update the Apache Reporter Tool: https://reporter.apache.org/addrelease.html?curator
7. Mark the version as released in JIRA
   1. Go here: https://issues.apache.org/jira/browse/CURATOR/?selectedTab=com.atlassian.jira.jira-projects-plugin:versions-panel
   2. Click the "Manage Versions" button
   3. Set the release date for the version
   4. Create a new Version and set the start date
   5. Exit administration mode by clicking "Overview" in the near-top-left area

Clean Up Old Releases

Per http://www.apache.org/dev/release.html#when-to-archive - remove old releases from the https://dist.apache.org/repos/dist/release/curator/ and https://dist.apache.org/repos/dist/dev/curator/ repos using svn rm.

How to Publish the Curator Website

Update the currentStableVersion in the main POM:

• Edit the root pom.xml
• Location currentStableVersion in the properties section
• Change to the current stable version
• Commit and push the change

To prepare for publishing the curator website, clone the master using git svn:

• cd to a directory of your choosing
• svn co https://svn.apache.org/repos/asf/curator/site/trunk curator-website

Assuming you have a clean compile/install of Curator, from the root of the Curator directory:

git checkout master
mvn site site:stage

Have a look at the staged site and make sure it's good. Then:

• cd to the curator-website directory
  • (optional) delete existing content: rm -fr *
• cp -r [curator source directory]/target/staging/* .

• Delete any old files from svn:

  • svn st | grep ^! | awk '{print " --force "$2}' | xargs svn rm

• Add any new files to svn:

  • svn add --force * --auto-props --parents --depth infinity -q 

• Commit the changes:

  • svn commit -m "Update for Curator version N.N.N"

You may need to make sure you've authenticated to the Apache Subversion server before you can push the site, else you may get an error along the lines of authorization failed: Could not authenticate to server: rejected Basic challenge. More reading material on how to secure your SVN credentials can be found here.

Also note if you get an error complaining that Server certificate verification failed: issuer is not trusted, you can add the repo certificate to the list of certificates accepted to your local svn client by simply listing the repository and accepting the cert permanently.

svn list https://svn.apache.org/repos/asf/curator/site/trunk

Error validating server certificate for 'https://svn.apache.org:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: *.apache.org
 - Valid: from Tue, 20 Dec 2011 00:00:00 GMT until Mon, 17 Feb 2014 23:59:59 GMT
 - Issuer: Thawte, Inc., US
 - Fingerprint: bc:5f:40:92:fd:6a:49:aa:f8:b8:35:0d:ed:27:5e:a6:64:c1:7a:1b
(R)eject, accept (t)emporarily or accept (p)ermanently? p