Page History

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

...

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

Publish your key

The key is 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"

...

#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"

...

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

...

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=RC00 # Set to the number of the current release candidate, starting at 0.

...

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 email matches the email for the key you want to use shown by gpg --list-secret-keys .

git tag -s "ozone-${VERSION}-$RC${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 git to use this program to prompt for signing: git config --global gpg.program "$(which gpg)"
3. Tell git which key to sign with: git config --global user.signingKey <gpg_key_id>
4. Tell gpg to use this program to prompt for passphrase: echo " passphrase: echo "pinentry-program $(which pinentry-mac)" > ~/.gnupg/gpg-agent.conf 
5. Reload gpg-agent: gpgconf --kill gpg-agent 

...

• Build the Release Tarballs. Make sure that Hugo is installed so that this step will also build the documentation. Also make sure you are using GNU-tar instead of BSD-tar.

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

...

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

cd "$RELEASE_DIR"

Calculate Calculate the checksum and sign the artifacts

cd "$RELEASE_DIR"
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

...

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. The Apache svn repo has a size limit for release artifacts. If uploading svn fails because the tarball is too big, we need to contact INFRA to increase our repo size. See here for details.
3. Verify signatures
   1. Download the KEYS file from  https://dist.apache.
   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).
      5. The git hash of the last commit the release was built on.
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

1. 1. This check is also run by the GitHub actions CI for each commit, so it should pass with no surprises.

Upload the artifacts dev staging area

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

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

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

...

<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 projectsReturn to your Ozone repository being used for the release, and run the following command:

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

Go to 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${RC}"

Vote

Send the voting mail to below mailing list

...

• 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.

. Review https://www.apache.org/legal/release-policy.html#release-approval for the ASF wide release voting policy. Note what is required of binding voters, and that binding votes can only come from PMC members. Sometimes responders will not specify whether or not their vote is binding. If in doubt check https://people.apache.org/committer-index.html. Users whose group membership includes ozone-pmc can cast binding votes.

Once voting is finished, send an email summarizing the results (binding +1s, non-binding +1s, -1s, 0s) and, if the vote passed, indicate 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 &Checkout the svn folder & commit the artifacts to a new directory.

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

cd 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:-m "commit msg" https://dist.apache.org/repos/dist/dev/ozone/"$VERSION" https://dist.apache.org/repos/dist/release/ozone/"$VERSION"

...

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  , and that the docs/current symlink has been updated to point to the latest release's directory.
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.

...

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

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

git push origin "ozone-${VERIONVERSION}"

Update the master branch

1. Cherry pick your commit updating the protolock files to a 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. 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 <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/

Publish a docker image for the release

The Ozone docker image is intended for testing purposes only, not production use. Therefore, it is ok to update this after announcing the release. An example pull request to update the docker image is here. The target branch for your pull request should be latest. After the pull request is merged, it can be published to docker hub by fast-forwarding the ozone-latest branch to match the latest branch.  Also, create a new branch named like ozone-1.5.0 (replace the version) and push it to GitHub.

git checkout ozone-latest
git pull
git merge --ff-only origin/latest
git checkout -b "ozone-${VERSION}"
git push origin ozone-latest "ozone-${VERSION}"

Patch Release

If there is a security vulnerability or critical bug uncovered in a major or minor Ozone release, a patch release may be necessary to fix this. The process is a bit simpler than a major or minor release, since there is already a solid foundation on the release's maintenance branch.

1. Cherry pick the fix(es) on to the maintenance branch. For example, for Ozone's 1.2.0 release, this is the branch called ozone-1.2.
2. Run all steps from the sections Update the versions through Publish a docker image for the release, with the following modifications:
   1.  Do not update the protolock files unless protocol buffers were changed as part of the fix.
   2. When updating the website, all instances of the original major/minor release should be replaced with this patch version, since we do not want users downloading the original release anymore.
      1. For example, any website text referring to 1.2.0 should be changed to refer to 1.2.1.
      2. Continuing the 1.2.0 → 1.2.1 example, the release/1.2.0 page should redirect to release/1.2.1.
      3. An example pull request to do this is here.
      4. The docs can be added to the website normally as described above in Update the ozone website. The docs link for the original major/minor release can remain alongside the docs link for the patch release.

In the event of a critical security vulnerability or seriously harmful bug with a small set of changes in the patch, PMC members may vote to forgo the usual 72 hour minimum time for a release vote and publish once there are enough binding +1s. 

Remove the previous patch release from Apache distribution site:

svn rm -m 'Ozone: delete old version 1.2.0' https://dist.apache.org/repos/dist/release/ozone/1.2.0

...

Update this document

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

...