How To Release

(The release process is still work in progress, please update this page as it gets refined)

Propose Release

1. A committer proposes a release and a release manager is chosen by the committers (normally the committer proposing the release would be the release manager).
2. Agree on the initial scope for the release and update JIRAs accordingly.

Create the Release Branch

A new release branch is created only for minors (X.Y.0) releases but not for patches (X.Y.Z). A patch is an update to an existing branch created for X.Y.0 (a patch release must be tagged).

1. Send email to dev@oozie.apache.org to notify that
   1. A new branch is about to be created from trunk
   2. Request to hold off any commits from trunk until further email.

2. Create a branch for the release. For example:

   $ git checkout origin master
   $ git checkout -b branch-4.0

3. Update the versions in the POMs in trunk, and the new branch if necessary. Use Maven versions plugin. For example:

   $ mvn versions:set -DnewVersion=4.0.0-SNAPSHOT
   

4. Push the new branch to the repository

   $ git push origin branch-4.0:branch-4.0

5. Do a search for all resolved jiras with fixVersion as trunk (JQL is "project = Oozie AND resolution = Fixed AND fixVersion = trunk"). Bulk edit them and change the fixVersion from trunk to the new branch version.
6. Send email to dev@oozie.apache.org to notify that the release branch has been created and that commits can resume both in trunk and in the new branch.

Work on the Release Branch

1. Work on existing JIRAs and new ones until the release manager feels that the branch is ready for a release.
2. As a general rule, JIRAs must be committed first to trunk and the backported to the branch. Only for cases where the JIRAs does not apply to trunk the JIRA should be only committed to the branch.

Preparing a Release

Update the POMs in the release branch with the final release version (typically this means removing the -SNAPSHOT) using the Maven versions plugin. For example:

$ mvn versions:set -DnewVersion=4.0.0

Commit the version change.

These steps are required for all the releases (such as major, minor, and patches).

1. Check out the branch with. For example:

   $ git checkout origin branch-4.0
   

2. Create a RAT report to verify all files have the corresponding Apache License header. For example:

   $ mvn apache-rat:check
   

3. Tag the release candidate, where R is the iteration number for this release candidate, starting with 0 and also push it to the repository:

   $ git tag -a release-4.0.0-rc0 -m "Oozie 4.0.0-rc0 release"
   $ git push origin release-4.0.0-rc0

Creating a Release Artifact

Tools required to crate a release artifact:

• svn client
• git client
• mvn
• md5sum (Linux) or md5 (OSX)
• gpg (you need to have your GPG keys set up as per the following instructions).

  • Generating key pair using the following command. You can simply accept all default settings and give your name, email and Passphase.

    $ gpg --gen-key
    

  • Export your fingerprint and public key.

    $ gpg --fingerprint "Your Name" ; gpg --armor --export 'Your Name'
    

  • Checkout from SVN https://dist.apache.org/repos/dist/release/oozie and append the output of the previous command to the KEYS file and commit the changes.

  • Export your private key, and keep it in a safe place.

    $ gpg --export-secret-key -a "Your Name" > private.key
    

1. Do a fresh checkout of branch to release. For example: 

   $ git checkout origin branch-4.0
   

2. Do a build running all test cases as a verification.

   $ bin/mkdistro.sh
   

3. Run the bin/create-release-artifact script to create the release artifact. For example:

   $ bin/create-release-artifact
   
   ...
   Release artifacts avail at /tmp/oozie.13501
   ----------------
   oozie-4.0.0.tar.gz
   oozie-4.0.0.tar.gz.asc
   oozie-4.0.0.tar.gz.md5
   rat_report
   release-log.txt
   ----------------

4. Copy release files to your Apache HTML directory. For example:

   $ ssh people.apache.org mkdir -p public_html/oozie-4.0.0-rc0
   $ scp -p /tmp/oozie.13501/* people.apache.org:public_html/oozie-4.0.0-rc0/
   

5. Call a release vote for the Oozie PMC members. This vote must receive a minimum of 3 Oozie PMC members +1s, and more +1s than -1s. The email should be sent to dev@oozie.apache.org. The mail should:
   1. Have a subject line "[VOTE] Release Oozie X.Y.Z (candidate #)" where X.Y.Z is the version number and a is the candidate number for this release.
   2. State what are new in this release.
   3. Tell where the keys used to sign the release can be found.
   4. State where the release, md5 signature, gpg signature, and rat report can be found.
   5. Request that users and developers download it, test it, and vote.

   6. State when the vote closes. The vote must remain open for at least 72 hours. It can be longer at your discretion (e.g. around major holidays).
      Here is a sample email:

      Subject: VOTE Release Oozie 4.0.0 (candidate 0)
      
      
      Hi,
      
      I have created a build for Oozie 4.0.0, candidate 0.
      
      Keys to verify the signature of the release artifact are available at
      
        http://www.apache.org/dist/oozie/KEYS
      
      Please download, test, and try it out:
      
        http://people.apache.org/~<YOU APACHE ID>/oozie-4.0.0-rc0
      
      The release, md5 signature, gpg signature, and rat report can all
      be found at the above address.
      
      Vote closes on <DATE>.
      
      <YOUR NAME>
      

If the vote passes, the release needs to be published. Before that, send a mail with subject line "[VOTE][RESULT] Release Oozie X.Y.Z (candidate #)"to dev@oozie.apache.org listing the binding (PMC) voters.

Subject: [VOTE][RESULT] Release Oozie 4.0.0 (candidate 3)

 
Hi,
Oozie 4.0.0 RC3 has passed the vote.

The vote tally is:
+1 --> x votes from Oozie PMC members (binding), y votes from Oozie Committers (non-binding), z votes from Oozie contributors (non-binding)
-1 --> 0 votes
 0 --> 0 votes

Publishing the Release Artifact

1. Tag and sign the release from the latest release candidate and push it to the repository. You should use the same key pair as used earlier when signing the RC, which should be in the gpg keyring.  For example:

   $ git tag -u "<gpg-username>" -s release-4.0.0 -m "Oozie 4.0.0 release" release-4.0.0-rc3
   $ git push origin release-4.0.0

   You can verify the release was properly signed with:

   $ git tag -v release-4.0.0

   If you are having trouble, you can check which keys are in your gpg keyring, and for what user, with:

   $ gpg --list-keys

2. Commit the release files to the https://dist.apache.org/repos/dist/release/oozie repository under a subdirectory named after the version. For example:

   $ svn co https://dist.apache.org/repos/dist/release/oozie oozie-releases
   $ cd oozie-releases
   $ mdkir 4.0.0
   $ cp ~/oozie-4.0.0-rc3/* 4.0.0/
   $ svn add 4.0.0
   
   $ svn commit -m "Adding Oozie 4.0.0 release artifacts"
   

3. Only the latest and currently being developed/maintained release(s) should be in the https://dist.apache.org/repos/dist/release/oozie repository.  You may need to delete older versions.  For example, if publishing the 4.0.1 release, the 4.0.0 release should be deleted.  And if we're no longer doing any more 3.x releases, all 3.x releases should be deleted.  However, if we're going to be doing development on 4.0.x and 4.1.x releases, then both should remain here.  The old releases can still be acquired from http://archive.apache.org/dist/oozie/<version> which you'll be updating the links to in the next step.  
4. Update the website
   1. Update the doap_Oozie.rdf file with the new release in the https://svn.apache.org/repos/asf/oozie/site/trunk branch
   2. Update the Releases and Documentation links in the Oozie content/site.xml file in the https://svn.apache.org/repos/asf/oozie/site/trunk branch.
      1. Only the latest and currently being developed/maintained release(s) should be at a http://www.apache.org/dyn/closer.cgi/oozie/<version> address
         The rest of the releases should be at a http://archive.apache.org/dist/oozie/<version> address
   3. Copy the Oozie release documentation to the resources/docs directory of the https://svn.apache.org/repos/asf/oozie/site/trunk branch.

   4. Generate and verify the new Oozie site.

      $ mvn site
      $ cd target/site
      

   5. After verifying the new site is correct, commit the changes (make sure to add the new documentation set to SVN).
   6. Publish Oozie site.
5. Wait until you see your changes reflected on the Apache Oozie web site, Apache downloads and mirrors downloads.

6. Send announcements to the Oozie user and developer aliases once the site changes are visible.

   Subject: [ANNOUNCE] Apache Oozie 4.0.0 released
   
    
    
   Hello Oozie community,
   
   The Apache Oozie team is pleased to announce the release of Oozie 4.0.0.
   Oozie 4.0.0 includes [new features,] bug fixes and minor improvements.
   
   The details of the release and download location can be found at http://oozie.apache.org
    
   [The full release notes can be found at the download location, but some highlights of this release include:
   - New feature 1
   - New feature 2
   - ...]
   
   Thanks to all developers, QA's, users, and committers for making this release happen.

   The parts in brackets are optional, and would only be used for releases with big new features; otherwise, they can be omitted.

Update JIRA

1. Goto JIRA and click on Administration tab (under the gear icon in the top right).
2. Select the Oozie project.
3. Select "Versions".
4. Hover over the version number that you released, click the gear icon and select "Release".
5. Enter the release date
6. If the next version does not exist (that is, if you are releasing version X.Y, if version X.Y+1 does not yet exist) create it using the Add Version box at the top of the page.
7. In JIRA, mark the issues resolved in this release as closed.
   1. Goto JIRA and click on the "Search for Issues" on "Issues" menu.
   2. In Project select "Oozie"
   3. In Status select "Resolved"
   4. In Resolutions select "Fixed"
   5. In Fix Version select the version you are releasing
   6. You should now have a list of the JIRAs fixed in the version you are releasing; you can double check it against the release-log.txt if you want
   7. Select "Tools->Bulk change all XX issues" (near the top right)
   8. Select all the issues and click on "Next"
   9. Select "Transition Issues" radio button and click on "Next"
   10. Select "Close Issue" radio button and click on "Next"
   11. Uncheck the box near the bottom at says "Send mail for this update" lest you spam every Oozie developer with a message for every bug resolved in this release. Click "Next".
   12. Also near the bottom is a place to put a comment; enter something like "Closing issue; Oozie x.y.z is released"
   13. Click on "Next"
   14. Click "Confirm". Don't worry if it gives you a HTTP 500 error, it still does the transitions.