Information/Recipes for Curator Committers
Tools/Preparation
Development
Releasing Curator
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/.
- Generate PGP code signing keys
- Ensure that your PGP signing keys are available in the KEYS file that is in the release folder /www/www.apache.org/dist/incubator/curator on people.apache.org
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).
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> ... </servers> <profiles> <profile> <properties> ... <curator-website-checkout-path>path-goes-here</curator-website-checkout-path> <gpg.keyname>id-of-your-pgp-key</gpg.keyname> ... </properties> ... <profile> ... <profiles> ... </settings>
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/.
Development
GitHub Flow
Curator loosely uses GitHub Flow. The short form of GitHub Flow is:
- Anything in the master branch is deployable
- To work on something new, create a descriptively named branch off of master (ie: new-oauth2-scopes)
- 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 a pull request
- After someone else has reviewed and signed off on the feature, you can merge it into master
- Once it is merged and pushed to 'master', you can and should deploy immediately
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:
- The binary artifacts must be staged
- The Apache release must be staged
- The release must be voted on
- If the vote succeeds:
- The Apache release must be promoted
- The binary artifacts must be released
Prepare the Release
- 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, executemvn release:clean
and then reset viagit reset --hard
. - 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 betweenpom.xml.tag
and its correspondingpom.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
- The release plugin will create
- 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
- You'll be prompted for the same version information and optionally your GPG
- Verify the staged artifacts in the Apache Nexus repository:
- Go to: https://repository.apache.org/index.html
- Enterprise > Staging
- Staging tab > Name column > curator
- Navigate through the artifact tree and double check things.
- Close the Nexus staging repo by clicking on the curator repo and clicking the "Close" button.
- IMPORTANT: Do NOT release the binaries yet
Stage the Apache Release
- Create the stageable source artifacts
- Checkout the release:
git checkout apache-curator-X.X.X-incubating
mvn -P apache-release clean install
git checkout master
- Checkout the release:
- Locate the artifacts in your local Maven repository. On Mac/*nix this will be
~/.m2/repository/org/apache/curator/apache-curator/...
. The remainder of the directory will be the version being released. In the directory you will find 4 files that need to be staged:- apache-curator-X.X.X-incubating-source-release.zip
- apache-curator-X.X.X-incubating-source-release.zip.asc
- apache-curator-X.X.X-incubating-source-release.zip.md5
- apache-curator-X.X.X-incubating-source-release.zip.sha1
scp
these files to yourpublic_html/staging directory/rcN/
in your home directory on people.apache.org
Initiate a Vote On the Release
- Create a pre-VOTE email thread on dev@curator.incubator.apache.org to record votes as replies (see Example Emails).
- This vote is to get a sense of the Curator PMC members
- The release needs 3 +1 votes from the PMC
- If this pre-VOTE succeeds, continue to the next step
- Regardless of the vote result, send a RESULT VOTE email (see Example Emails).
- Create a VOTE email thread on @general to record votes as replies (see Example Emails).
- If the Vote succeeds, you can promote the release
- Regardless of the vote result, send a RESULT VOTE email (see Example Emails).
Promote the Release
- Create a directory for the release on people.apache.org at
/www/www.apache.org/dist/incubator/curator
namedapache-curator-X.X.X-incubating
(replace X.X.X with the version). mv
the staged files from your public_html/staging directory on your home directory on people.apache.org to this new directory- Release the binary artifacts
- Go to: https://repository.apache.org/index.html
- Select the curator release and click the "Release" button.
- Announce the release on the @general list (see Example Emails).
How to Publish the Curator Website
Assuming you have a clean compile/install of Curator, from the root of the Curator directory:
mvn site site:stage
Have a look at the staged site and make sure it's good. Then:
mvn site-deploy