This page is to document the release procedure for HCatalog. HCatalog is currently a Apache incubator project. Its release process is work in progress and is modeled from Apache Pig Release.

Note that only HCatalog committers can create a release.

Preparation

Prior to starting an HCatalog release, please familiarize yourself with the following:

Apache Releases Policy
Apache Publishing Releases guide

TODO:

Define issue management process like assigning/removing issues from release.
Need to integrate javadoc into this.

Creating Release Branch

We only branch for major (X.0.0) and minor(X.Y.0) releases but not for patches (X.Y.Z). Patch is and update to an existing branch created for X.Y.0.

Send email to hcatalog-dev@incubator.apache.org to notify that you about to branch the tree and ask to hold off any commits till this is finished.
Update CHANGES.txt to include the release version and date (use Unreleased for the date if it is unknown) and remove Trunk (unreleased changes). Below is the example of the top of the CHANGES.txt file after the update:
```
Apache HCatalog Change Log

Release 0.1.0 - Unreleased

  INCOMPATIBLE CHANGES

  NEW FEATURES
    HCAT-1. Upload initial code to HCatalog (gates)
```
Edit src/docs/src/documentation/content/xdocs/site.xml. In the external reference for api where the link contains the previous version number change this string to the correct version number.

Commit these changes to trunk:

svn commit -m "Preparing for release X.Y.Z"

Create a branch for the release series:

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

Update CHANGES.txt to add back in Trunk (unreleased changes). Top of the CHANGES.txt should look like this now:

HCatalog Change Log

Trunk (unreleased changes)

  INCOMPATIBLE CHANGES

  IMPROVEMENTS

  OPTIMIZATIONS

  BUG FIXES

Release 0.1.1 - Unreleased
....

Update the default version in build.xml on trunk to X.Y+1.0-dev.

Commit these changes to trunk:

svn commit -m "Preparing for X.Y+1.0 development"

Updating Release Branch

The steps in this section are needed for all the releases (major, minor, and patches).

Check out the branch with:

svn co https://svn.apache.org/repos/asf/incubator/hcatalog/branches/branch-X.Y

Run rat report and make sure that all files that can have apache license agreement. Note that currently the rat report is part of output and needs to be manually extracted. TODO: write the report into a file.
```
    ant -Dforrest.home=<forrest installation dir> releaseaudit > rat_report
```
Save the rat_report file, you will need it later
For patches, update CHANGES.txt to include the release version and date. See #2 from Create Release Branch section.
Update RELEASE_NOTES.txt for this release:
1. Make sure to change all of the version number references to the current version number.
2. Note highlights for this release. CHANGES.txt is a great place to find these.
3. Note incompatibilities for this release. These should be listed under INCOMPATIBLE CHANGES in CHANGES.txt.
Update the version number in build.xml to be X.Y.N-dev, where N is one greater than the release being made.

Commit these changes:

    svn commit -m "Preparing for release X.Y.Z"

Tag the release candidate, where R is the iteration number for this release candidate, starting with 0:

    svn copy https://svn.apache.org/repos/asf/incubator/hcatalog/branches/branch-X.Y \
    https://svn.apache.org/repos/asf/incubator/hcatalog/tags/release-X.Y.Z-rcR -m "HCatalog X.Y.Z-rcR release."

Building

Build the release and run unit tests:

    umask 0022
    ant clean
    ant test
    ant -Dhcatalog.version=X.Y.Z-incubating -Dforrest.home=<Forrest installation dir>  src-release

Test the tar file by unpacking the release and
1. building hcatalog.jar: ant
2. running unit tests ant test

Generate the MD5 checksum of the release file:

    cd build
    md5sum hcatalog-X.Y.Z-incubating.tar.gz > hcatalog-X.Y.Z-incubating.tar.gz.md5

If you do not have a gpg key pair, do the following steps:

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 public key.

        gpg --armor --output pubkey.txt --export 'Your Name'

Open pubkey.txt, copy the full text and append it to the following files by pasting, then commit these changes:

        https://svn.apache.org/repos/asf/incubator/hcatalog/branches/branch-X.Y.Z/KEYS
        https://svn.apache.org/repos/asf/incubator/hcatalog/trunk/KEYS

Upload updated KEYS to Apache.

        scp KEYS people.apache.org:/www/www.apache.org/dist/incubator/hcatalog/KEYS

Export your private key, keep it with you.

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

Sign the release (see Step-By-Step Guide to Mirroring Releases for more information).

    gpg --armor --output hcatalog-X.Y.Z-incubating.tar.gz.asc --detach-sig hcatalog-X.Y.Z-incubating.tar.gz

Verify gpg signature.

    gpg --import KEYS  (if necessarily)
    gpg --verify hcatalog-X.Y.Z-incubating.tar.gz.asc hcatalog-X.Y.Z-incubating.tar.gz

Copy release files to a public place (usually into public_html in your home directory):

    ssh people.apache.org mkdir public_html/hcatalog-X.Y.Z-incubating-candidate-0
    scp -p hcatalog-X.Y.Z-incubating.tar.gz* people.apache.org:public_html/hcatalog-X.Y.Z-incubating-candidate-0
    cd ..
    scp RELEASE_NOTES.txt people.apache.org:public_html/hcatalog-X.Y.Z-incubating-candidate-0
    scp rat_report people.apache.org:public_html/hcatalog-X.Y.Z-incubating-candidate-0

The rat_report is the report generated in the Updating Release Branch section above.

Call a release vote for the Podling PMC (PPMC). This vote must receive a minimum of 3 PPMC members +1s, and more +1s than -1s. The email should be sent to hcatalog-user@incubator.apache.org. The mail should:
- have a subject line "[VOTE] Release HCatalog X.Y.Z-incubating (candidate a)" where X.Y.Z is the version number and a is the candidate number for this release.
- State what is new in this release.
- Tell where the keys used to sign the release can be found.
- State where the release, md5 signature, gpg signature, and rat report can be found.
- Request that users and developers download it, test it, and vote.
- 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 HCatalog 0.1.0-incubating (candidate 0)

    Hi,

    I have created a candidate build for HCatalog 0.1.0-incubating. This is the initial release of HCatalog.

    Keys used to sign the release are available at http://svn.apache.org/viewvc/incubator/hcatalog/trunk/KEYS?view=markup.

    Please download, test, and try it out:

    http://people.apache.org/~you/hcatalog-0.1.0-incubating-candidate-0

    The release, md5 signature, gpg signature, and rat report can all be found at the above address.

    Should we release this? Vote closes on Thursday, June 16th.

    Me
```
If the PPMC approves the release, call an Incubator PMC (IPMC) vote. This vote must receive a minimum of 3 IPMC member +1s, and more +1s than -1s. The email sent should look similar.

Publish

If both votes pass, the release needs to be published.

Tag the release:

    svn move https://svn.apache.org/repos/asf/incubator/hcatalog/tags/release-X.Y.Z-rcR \
    https://svn.apache.org/repos/asf/incubator/hcatalog/tags/release-X.Y.Z -m "HCatalog X.Y.Z release."

Copy release files to the distribution directory and make them writable by the hcatalog group.

    ssh people.apache.org
    cp -pr public_html/hcatalog-X.Y.Z-incubating-candidate-0 /www/www.apache.org/dist/incubator/hcatalog/hcatalog-X.Y.Z-incubating
    cd /www/www.apache.org/dist/incubator/hcatalog
    chgrp -R incubator hcatalog-X.Y.Z-incubating
    chmod -R g+w hcatalog-X.Y.Z-incubating

The release directory usually contains just two releases, the most recent from two branches, with a link named 'stable' to the most recent recommended version.

    ssh people.apache.org
    cd /www/www.apache.org/dist/incubator/hcatalog
    rm -rf hcatalog-A.B.C-incubating; rm stable
    ln -s hcatalog-X.Y.Z-incubating stable

Wait 24 hours for release to propagate to mirrors.

Prepare to edit the website.

    svn co https://svn.apache.org/repos/asf/incubator/hcatalog/site

Update the front page news in author/src/documentation/content/xdocs/index.xml.
Update the release news in author/src/documentation/content/xdocs/releases.xml.
Update the documentation links in author/src/documentation/content/xdocs/site.xml

Copy in the release specific documentation. releasedir in the following is the directory where you built the release version of HCatalog

        cd publish
        mkdir docs/rX.Y.Z
        cp -pr <releasedir>/build/hcatalog-X.Y.Z-incubating/docs/* publish/docs/rX.Y.Z/
        svn add publish/docs/rX.Y.Z

We should only be publishing release specific documentation for releases still available for download. If you removed any releases from /www/www.apache.org/dist/incubator/hcatalog several steps ago, then you should also use svn rm to remove the associated documents from docs.
Regenerate the site, review it and commit in HowToCommit.

Deploy your site changes.

    ssh people.apache.org
    cd /www/incubator.apache.org/hcatalog
    svn up

Wait until you see your changes reflected on the Apache web site.

Send announcements to the user and developer lists as well as (general@haoop.apache.org) once the site changes are visible.

    The HCatalog team is happy to announce the release of HCatalog X.Y.Z.

    Apache HCatalog provides a table management service for Hadoop.
    More details about HCatalog can be found at http://incubator.apache.org/hcatalog.

    The highlights of this release are ... The details of the release can be found at http://incubator.apache.org/hcatalog/releases.html.

In JIRA, mark the release as released.
1. Goto JIRA and click on Administration tab.
2. Select the HCatalog project.
3. Select Manage versions.
4. Select Release for the version you have released.
5. If a description has not yet been added for the version you are releasing, select Edit Details and give a brief description of the release.
6. If the next version does not exist (that is, if you are releasing version 0.x, if version 0.x+1 does not yet exist) create it using the Add Version box at the top of the page.
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 the left hand Edit section, set Project to HCatalog.
3. In Status select "Resolved"
4. In Resolutions select "Fixed"
5. Click "Search" button
6. In the next screen, further select fix For select the version you are releasing.
7. Click on the "Search" button
8. Select "Tools->Bulk change all XX issues" (near the top right)
9. Select all the issues and click on "Next"
10. Select "Transition Issues" radio button and click on "Next"
11. Select "Close Issue" radio button and click on "Next"
12. Uncheck the box near the bottom at says "Send mail for this update" lest you spam every HCatalog developer with a message for every bug resolved in this release. Click "Next".
13. Click "Confirm". Don't worry if it gives you a HTTP 500 error, it still does the transitions.

Update jdiff for next release (We don't have jdiff set up yet, but these next several instructions are left here so when we do we can use them)

       svn co https://svn.apache.org/repos/asf/incubator/hcatalog/trunk

Open build.xml. Change this line:

    <property name="jdiff.stable" value="X.Y-1.Z"/>
    To
    <property name="jdiff.stable" value="X.Y.Z"/>

Copy jdiff comparison base to trunk

    cp {releasedir}/lib/jdiff/hcatalog_X.Y.Z.xml lib/jdiff

    svn add lib/jdiff/hcatalog_X.Y.Z.xml
    svn remove lib/jdiff/hcatalog_X.Y-1.Z.xml
    svn commit -m "Jdiff change for X.Y.Z"

Child pages

HowToRelease

Preparation

Creating Release Branch

Updating Release Branch

Building

Publish