How to do a release

Pre-Reqs

1. Make sure that the JIRAs included in the release have their fix-version and release notes fields set correctly, and are resolved. The script will query them, and create the CHANGES and RELEASE_NOTES files from that information. Use the dev/misc_utils/git_jira_fix_version_check.py script to find the discrepancies between the commits and the JIRAs.
2. Make sure you have set up your user for release signing. Details http://www.apache.org/dev/release-signing.html.
3. Make sure you have set up maven for deploying to the ASF repo. Details https://infra.apache.org/publishing-maven-artifacts.html
4. Clone the phoenix master branch locally (the script will download the actual repo to release itself)
5. Make sure docker is running locally

Note that Docker Desktop for Mac works, but will be slow. (Several hours for for a phoenix (core) release ). Running on a native Linux machine is much faster, as you do not incur the filesystem translation layer penalty

Do a dry run

Read /dev/create_release/README.txt to get an idea of what the script does, and how to set up gpg-agent for signing.

Run the dev/create-release/do-release-docker.sh -d <workdir> -p <project> command, where

• <project> is the repo name you’re releasing from (i.e. phoenix)
• <workdir> is any existing directory that can be deleted

The script will ask a number of questions. Some of them will have intelligent default, but make sure you check them all:

  [stoty@IstvanToth-MBP15:~/workspaces/apache-phoenix/phoenix (PHOENIX-6307)$]dev/create-release/do-release-docker.sh -p phoenix -d ~/x/phoenix-build/
  Output directory already exists. Overwrite and continue? [y/n] y
  ========================
  === Gathering release details.
  
  PROJECT [phoenix]:
  GIT_BRANCH []: master
  Current branch VERSION is 5.1.0-SNAPSHOT.
  RELEASE_VERSION [5.1.0]:
  RC_COUNT [0]:
  RELEASE_TAG [5.1.0RC0]:
  This is a dry run. If tag does not actually exist, please confirm the ref that will be built for testing.
  GIT_REF [5.1.0RC0]:
  ASF_USERNAME [stoty]:
  GIT_NAME [Istvan Toth]:
  GPG_KEY [stoty@apache.org]:
  We think the key 'stoty@apache.org' corresponds to the key id '0x77E592D4'. Is this correct [y/n]? y
  ================
  Release details:
  GIT_BRANCH:      master
  RELEASE_VERSION: 5.1.0
  RELEASE_TAG:     5.1.0RC0
  API_DIFF_TAG:
  ASF_USERNAME:    stoty
  GPG_KEY:         0x77E592D4
  GIT_NAME:        Istvan Toth
  GIT_EMAIL:       stoty@apache.org
  DRY_RUN:         yes
  ================

• PROJECT: the repo to release (default specified by -p on the command line)
• GIT_BRANCH: the git branch to use for release. This can be master, or a pre-created release branch.
• RC_COUNT: the RC number, starting from 0
• RELEASE_TAG: the git tag the the script will tag the RC commit with.
• ASF_USERNAME: your ASF username, for publishing the release artifacts.
• ASF_PASSOWORD: your ASF password, only for non-dry runs
• GIT_NAME/GIT_EMAIL: will be used for the RC commit
• GPG_KEY: id for you GPG key. The script will offer a GPG secret key from your key ring, double check that it is your code signing key, and correct it if it is not.

The dry-run will generate the signed release files into <workdir>/output directory. The maven artifacts will be in <workdir>/output/phoenix-repo-XXXX local maven repo, in the usual structure

Create real RC

If the dyr-run release artifacts (source, binary, and maven) check out, then do publish a real RC to ASF

Repeat the dry run process, but add the -f switch to the do-release-docker.sh command.

The script will upload the source and binary release artifacts to a directory under https://dist.apache.org/repos/dist/dev/phoenix/ The script will also deploy the maven artifacts to https://repository.apache.org/#stagingRepositories Check that these are present.

Voting

1. Initiate the vote email. See example here, or use the <workdir>/output/vote.txt template generated by the script.
2. In case the RC (Release Candidate) is rejected via the vote, you will have to repeat the above process and re-initiate the vote for the next RC (RC0, RC1, etc.).

Release

1. Once voting is successful (say for RC1), copy artifacts to https://dist.apache.org/repos/dist/release/phoenix:

   svn mv https://dist.apache.org/repos/dist/dev/phoenix/apache-phoenix-4.15.0-HBase-1.3-rc1      
          https://dist.apache.org/repos/dist/release/phoenix/apache-phoenix-4.15.0-HBase-1.3
   

2. Set release tag and commit:

   git tag -a v4.15.0-HBase-1.3 v4.15.0-HBase-1.3-rc1 -m "Phoenix v4.15.0-HBase-1.3 release"
   

3. Remove any obsolete releases on https://dist.apache.org/repos/dist/release/phoenix given the current release.

4. Go to https://repository.apache.org/#stagingRepositories and close -> release the staged artifacts (takes a while so you may need to refresh multiple times).
5. Create new branch based on current release if needed, for ex: 4.15 branches in this case.

6. Set version to the upcoming SNAPSHOT and commit:

   mvn versions:set -DnewVersion=4.16.0-HBase-1.3-SNAPSHOT -DgenerateBackupPoms=false
   

7. If releasing Phoenix (core) Create a JIRA to update PHOENIX_MAJOR_VERSION, PHOENIX_MINOR_VERSION and PHOENIX_PATCH_NUMBER in MetaDataProtocol.java appropriately to next version (4, 16, 0 respectively in this case) and compatible_client_versions.json file with the client versions that are compatible against the next version ( In this case 4.14.3 and 4.15.0 would be the backward compatible clients for 4.16.0 ). This Jira should be committed/marked with fixVersion of the next release candidate.

8. Add documentation of released version to the downloads page and wiki.
9. Update the Apache Committee Report Helper DB
10. Send out an announcement email. See example here.
11. Bulk close Jiras that were marked for the release fixVersion.

Congratulations!