Ozone Release Guideline

This document describes the process to release Apache Ozone. The process is not yet scripted, and the documentation is a work in progress

Pre-Requisite

The release manager should have a gpg key setup to sign the artifacts. For more details refer to below link. 

https://www.apache.org/dev/new-committers-guide.html#set-up-security-and-pgp-keys

Publish your key

The key supposed to be published together with the release. Please append it to the end of KEYS files:

https://dist.apache.org/repos/dist/release/ozone/KEYS

svn co https://dist.apache.org/repos/dist/release/ozone
cd ozone
export CODESIGNINGKEY=your_gpg_key_id
gpg --list-sigs $CODESIGNINGKEY >> KEYS
gpg --armor --export $CODESIGNINGKEY >> KEYS
svn commit -m "ozone: adding key of XXXX to the KEYS"

In case you are only a committer and not a PMC member, you can add your key to the dev KEYS file and a PMC can move it to the final destination

#use latest KEYS as the base
svn rm https://dist.apache.org/repos/dist/dev/ozone/KEYS
svn cp https://dist.apache.org/repos/dist/release/ozone/KEYS  https://dist.apache.org/repos/dist/dev/ozone/KEYS

svn co https://dist.apache.org/repos/dist/dev/ozone
cd ozone
export CODESIGNINGKEY=your_gpg_key_id
gpg --list-sigs $CODESIGNINGKEY >> KEYS
gpg --armor --export $CODESIGNINGKEY >> KEYS
svn commit -m "ozone: adding key of XXXX to the KEYS"

Pre-Vote

Create a parent Jira for the release

This provides visibility into the progress of the release for the community. Tasks like cherry-picking fixes on to the release branch, updating the ozone website, publishing the docker image, etc can be added as subtasks.

Bulk comment on Jiras targeting this release

Issue a Jira query like this, modified for the release number you are working with, to find all unresolved Jiras that have the target version field set to this release. Note that some people incorrectly use Fix Version as the Target Version, so Fix Version is included in this search. Use the following steps to issue a bulk update to these Jiras:

1. In the top right corner, click Tools  and under Bulk Change , select all ... issues .
2. Click the top check box to select all the issues. Click Next .
3. Select Edit Issues , then click Next .
4. Select Change Fix Version/s , and in the drop down select Clear field .
   1. This corrects unresolved issues which incorrectly set a fix version for this release.
5. Select Change Target Version/s , and enter the version of the release after the one you are managing.
6. Select Change Comment , and add a comment saying that you have moved the release field out, but if the issue is being actively worked on, is close to completion, and would like to be included in this release, to contact you by a given date, probably a week in the future.
   1. Note that even though the action is called Change Comment , it actually adds a comment to the Jira and does not affect existing comments.
7. Keep clicking through until the operation is started. It may take a while for Jira to finish the bulk update once it is started.

Branching

After the date specified in the Jira comments has passed and blocking issues have been resolved, you can create a release branch in the main apache/ozone github repo. Name the branch after the major and minor version of the release, so patch releases can also be done off this branch. For example, If releasing 1.2.0, create a branch called ozone-1.2 . All release related changes will go to this branch until the release is complete, after which some changes mentioned below will be cherry picked to master .

Set up local environment

The following variables will be referenced in commands.

export VERSION=1.1.0 # Set to the version of ozone being released.

export RELEASE_DIR=~/ozone-release/ # ozone-release needs to be created

export CODESIGNINGKEY=<your_gpg_key_id>

export RC=RC0 # Set to the number of the current release candidate, starting at 0.

It is probably best to clone a fresh ozone repository locally to work on the release, and leave your existing repository intact for dev tasks you may be working on simultaneously. After cloning, make sure the apache/ozone upstream repo is named origin . This is required for release build metadata to be correctly populated. Assume all following commands are executed from within this repo with your release branch checked out.

Reset the git repository

git reset --hard

git clean -dfx

Update the versions

Use below command or use IDE to replace "${VERSION}-SNAPSHOT" with "${VERSION}".

find . -name pom.xml -type f | xargs sed -i "s/${VERSION}-SNAPSHOT/${VERSION}/g"

find . -name pom.xml -type f -print0 | xargs -0 sed -i '' "s/${VERSION}-SNAPSHOT/${VERSION}/g"

Commit the changes

git commit -am "Update Ozone version to $VERSION"

Build and commit the proto.lock change

Protolock files are used to check backwards compatibility of protocol buffers between releases. The ozone build checks protocol buffers against these lock files and fails if an incompatibility is detected. They should be updated for each release, and require protolock to be installed. Save and run the following script from your ozone repo root, and then commit the changed files to git. Double check that only files called proto.lock are being committed, and that the changes to the files makes sense based on new features added in this release.

#!/usr/bin/env sh

for lock in $(find . -name proto.lock); do
    lockdir="$(dirname "$lock")"
    protoroot="$lockdir"/../proto
    if protolock status --lockdir="$lockdir" --protoroot="$protoroot"; then
        protolock commit --lockdir="$lockdir" --protoroot="$protoroot"
    else
        echo "protolock update failed for $protoroot"
    fi
done

git commit -m "update proto.lock for Ozone $VERSION"

Tag the commit for the release candidate

This will sign the tag with the gpg key matching the git mailing address. Make sure that the email given by git config user.name matches the email for the key you want to use shown by gpg --list-secret-keys .

git tag -s "ozone-${VERSION}-${RC}"

If the command fails on MacOS, you may need to do the following additional steps:

1. Install a program to prompt you for your gpg key passphrase (example using homebrew): brew install pinentry-mac 
2. Tell gpg to use this program to prompt for passphrase: echo "pinentry-program $(which pinentry-mac)" > ~/.gnupg/gpg-agent.conf 
3. Reload gpg-agent: gpgconf --kill gpg-agent 

Create the release artifacts

• Run rat check and ensure there are no failures.

./hadoop-ozone/dev-support/checks/rat.sh

• Clean the Repo of all Rat output

git reset --hard

git clean -dfx

• Build the Release Tarballs. Make sure that Hugo is installed so that this step will also build the documentation.

mvn clean install -Dmaven.javadoc.skip=true -DskipTests -Psign,dist,src -Dtar -Dgpg.keyname="$CODESIGNINGKEY"

• Now that we have built the release artifacts, we will copy them to the release directory.

cp hadoop-ozone/dist/target/ozone-*.tar.gz "$RELEASE_DIR"/

cd "$RELEASE_DIR"

Calculate the checksum and sign the artifacts

for i in $(ls -1 *.tar.gz); do gpg  -u "$CODESIGNINGKEY" --armor --output "${i}.asc" --detach-sig "$i"; done

for i in $(ls -1 *.tar.gz); do sha512sum "$i" > "${i}.sha512"; done

for i in $(ls -1 *.tar.gz); do gpg --print-mds "$i" > "${i}.mds"; done

 Now each .tar.gz file should have an associated .mds file, .asc file, and .sha512 file

Check the artifacts

Before uploading the artifacts, run some basic tests on them, similar to what other devs will run before voting in favor of the release.

1. Extract the contents of the source tarball and build it with an empty maven cache by renaming your ~/.m2 directory before doing the build.
2. Check the size of the output binary tarball for significant size increase from the last release.
   1. The Apache servers currently have a limit of 350mb for release artifacts.
   2. A significant increase in size could indicate a dependency issue that needs to be fixed.
3. Verify signatures
   1. Download the KEYS file from  https://dist.apache.org/repos/dist/release/ozone/KEYS
   2. Import its contents (which should include your public gpg key): gpg --import KEYS 
   3. Verify each .tar.gz artifact: gpg --verify <artifact>.tar.gz.asc <artifact>.tar.gz 
4. Verify checksums
   1. Run shasum -a 512 *.tar.gz 
   2. Verify that the output checksums for each artifact match the contents of its .sha512 file and the SHA512 line in its .mds file.
5. Make sure docs are present in the release tarball
   1. There should be a directory called docs in the top level. If there is not, then hugo  was not installed during the build and it must be re-done.
   2. Extract the release and open docs/index.html in your web browser, and check that the documentation website looks ok.
6. Check the output of running  bin/ozone version  from the extracted release tarball
   1. After extracting the release, the output of this command should contain:
      1. The correct release
      2. The correct national park tag
      3. A non-snapshot version of Ratis.
      4. A link to the apache/ozone GitHub repository (not your fork).
7. Run the Ozone upgrade acceptance tests by running test.sh  from the compose/upgrade directory in the extracted release tarball.

Upload the artifacts dev staging area

•  Upload everything from the $RELEASE_DIR to the dev staging area.

svn mkdir https://dist.apache.org/repos/dist/dev/ozone/"${VERSION}-${RC}"
svn co  https://dist.apache.org/repos/dist/dev/ozone/"${VERSION}-${RC}"
cd "${VERSION}-${RC}"
svn add *
svn commit -m "Ozone $VERSION $RC"

• Check the results using your browser by connecting to https://dist.apache.org/repos/dist/dev/ozone/

Upload the artifacts to the apache nexus

Double check if your apache credentials are added to your local ~/.m2/settings.xml

<settings>
  <servers>
	<server>
      <id>apache.snapshots.https</id>
      <username>your_apache_id</username>
      <password>your_apache_password</password>
    </server>
    <!-- To stage a release of some part of Maven -->
    <server>
      <id>apache.staging.https</id>
      <username>your_apache_id</username>
      <password>your_apache_password</password>
	</server>
  </servers>
</settings>

Do a maven deploy from the ozone and hdds projects

mvn deploy -Psign -pl '!:ozone-dist' -DskipTests -Dbuildhelper.skipAttach

Go https://repository.apache.org/#stagingRepositories and close the newly created orgapacheozone repository.

Push the release candidate tag to github

git push origin "ozone-${VERSION}-${RC}"

Vote

Send the voting mail to below mailing list

dev@ozone <dev@ozone.apache.org>

Include the following items in the email:

• Link to the release candidate tag on Github
• Link to a Jira query showing all resolved issues for this release. Something like this.
• Location of the source and binary tarballs. This link will look something like https://dist.apache.org/repos/dist/dev/ozone/1.2.0-rc0/
• Location where the maven artifacts are staged. This link will look something like https://repository.apache.org/content/repositories/orgapacheozone-1001/
• Link to the public key used to sign the artifacts. This should always be in the KEYS file and you can just link to that: https://dist.apache.org/repos/dist/dev/ozone/KEYS
• Fingerprint of the key used to sign the artifacts.

If no issues are found with the artifacts, let the vote run for 7 days. Once you have at least 3 binding +1 votes, send an email summarizing the results (binding +1s, non-binding +1s, -1s, 0s) and indicating that the release artifacts will be published. If an issue is found with the artifacts, apply fixes to the release branch and repeat the steps starting from tagging the commit for the release candidate with the $RC variable incremented by 1 for all steps.

After-Vote

Publish the artifacts

You should commit the artifacts to the SVN repository. If you are not a PMC member you can commit it to the dev zone first and ask a PMC for the final move.

Checkout the svn folder & commit the artifacts to a new directory.

svn checkout https://dist.apache.org/repos/dist/dev/ozone

svn mkdir "$VERSION"

cp "$RELEASE_DIR"/* "$VERSION"/

svn add "$VERSION"/*

svn commit -m "Added ozone-$VERSION directory"

PMC members can move it to the final location:

svn mv https://dist.apache.org/repos/dist/dev/ozone/"$VERSION" https://dist.apache.org/repos/dist/release/ozone/"$VERSION"

To publish the artifacts to the central maven, login to https://repository.apache.org/#stagingRepositories, select your staging repository and release it.

Write a haiku

Check the tag from the Ozone Roadmap page (it's a national park).

Find a photo which is under the CC license.

Write a haiku to the photo with Future font.

Update the ozone website

1. Create release notes and add them to the Ozone website with your haiku image. An example pull request showing how to do this is here. Note that the target branch is master .
2. Extract the docs folder from the release tarball, and add its contents to the website. An example pull request for this is here. Note that the target branch is asf-site .
3. Test the website locally by running hugo serve  from the repository root with the master branch checked out. Check that links for the new release are working. Links to the documentation will not work until the PR to the asf-site  branch is merged.

Add the final git tag and push it

git checkout "ozone-${VERION}-${RC}"

git tag -s "ozone-${VERION}" -m "Ozone $VERSION release"

git push "ozone-${VERION}"

Update the master branch

1. Cherry pick your commit updating the protolock files to a branch on your fork, and merge it to master with a pull request.
2. Update the Ozone SNAPSHOT version and national park tag on master with a pull request. Here you will pick the national park to use for the next release of Ozone and set it in the project's top level pom at /project/properties/ozone.release. Example

Update the Ozone Roadmap

1. Update the Ozone Roadmap so that the release notes for the just completed release are correct.
2. Move its row to the Past Releases  section.
3. Create a row for the next release in the Upcoming Releases  section, and add planned features that you are aware of.

Write an announcement mail to the Ozone mailing lists

Include the following links:

1. Release notes: https://ozone.apache.org/release/1.2.0/.  Replace the version in the URL with the version being released.
2. Download link: https://ozone.apache.org/downloads/
3. Link to versioned documentation: https://ozone.apache.org/docs/

Update this document

After finishing the release process, update this page to fix any mistakes, unclear steps, or outdated information.