Page tree
Skip to end of metadata
Go to start of metadata

When Quickstep updates with new functionality or improvements, we release quickstep as a tarball. A release manager is responsible for executing this process.

Release Managers

Release managers is a self-selected committer whose responsibility it is to go through this release process. This involves creating the release artifacts, counting votes, and publishing release artifacts. This is covered in detail below.

Step-by-step Release Guide

SVN Repo for release candidates: https://dist.apache.org/repos/dist/dev/incubator/quickstep

SVN Repo for final releases: https://dist.apache.org/repos/dist/release/incubator/quickstep

Prerequisites

As a release manager, you have a couple of base steps which will not be repeated after you go through this process once. 

  • Set up your apache email

  • Set up your apache gpg key [how-to guide]

    • Created a pgp key using your apache username. Per Apache, this must be on your hardware.

    • Uploaded it to a public keyserver

    • Added it to the KEYS file in the dev svn repo. Later, you will add it to the rel svn repo

    • [optional] Made sure someone in the group has validated your key

Overview

  1. Release Candidate Phase
    1. Make and publish a release candidate
      1. Select a commit to base the release
      2. Branch and tag the commit
      3. Create the release artifacts
      4. Publish the release artifacts to the dev SVN repo
    2. Vote on the release candidate
      1. Send a VOTE email
      2. Wait 72 hours
      3. Send a follow up email with results
      4. IF Vote passes, GOTO 2. ELSE GOTO 1
  2. Release Phase
    1. Vote on general.AT.incubator.apache.org

1. Release Candidate Phase

In this phase, we decide which commits will go into the release. We publish dev artifacts and the community votes if it should progress to a final release. Releases have a version (x.y.z) and candidates have a candidate version (rcX). See this SO post about version naming. There can be multiple candidates but only one release.

a. Make and publish a release candidate

These steps are somewhat covered in the script in the release/ folder of quickstep. The individual steps below explain what happens in the script. Also, the script must be modified to do some of things covered here. It's a rough guide.

i. Select a commit to base the release

You will create a release branch if this is the first release candidate. Otherwise, checkout the current release branch.

 

git checkout $COMMIT_HASH_YOU_CHOSE
git checkout -b branch-x.y.z
git push apache branch-x.y.z

ii. Branch and tag the commit

Test the branch and add commits as needed. If you are on a non-supported platform (mac), use a linux box or docker to test your release. A quickstep Dockerfile can be found here. Once you are happy with the candidate, tag the branch and push the update.

 
git fetch apache # to make sure you have the latest master
git checkout apache/branch-x.y.z
git checkout -b x.y.z-patch-foo # the name doesn't matter - it will only be in your local workstation
git cherry-pick b4d1a3... # or whatever git hashes
# then resolve conflicts, if there are any
# cherry-pick some more commits:
git cherry-pick ....
git cherry-pick .....
git push apache HEAD:branch-x.y.z
Do the tag
git fetch apache
git checkout apache/branch-x.y.z
git tag -a x.y.z-rcw -m "x.y.z release candidate w" # when making release candidate w of version x.y.z
git push apache x.y.z-rcw

iii. Create the release artifacts

This step involves several steps. First, you create the tarball. Next you will create hashes, and a signature. Full details are provided in the script.

You should also verify that every source file has an Apache-approved header. Apache has a script for this process, it's called apache rat.

iii. Publish the release artifacts to the dev SVN repo

svn checkout https://dist.apache.org/repos/dist/dev/incubator/quickstep/cd quickstep/

# The directory layout is x.y.z/RCw, where w is the release candidate number - RC1 is the first candidate, RC2 the second, and so on.
mkdir -p x.y.z/RCw
cd x.y.z/RCw
cp /tmp/apache-quickstep-incubating-x.y.z.tar.gz* ./
svn add .
svn commit --username=YOUR_APACHE_USER_NAME -m "Quickstep-x.y.z RCw"

b. Make a vote on the Release Candidate

There is a template for creating these emails here. Otherwise, follow these guidelines:

    1. Have a subject that starts with "[VOTE]"
    2. Explain what the vote is about
    3. Explain how to find the artifacts for testing, and include the tag and git tree hash (not release hash!) they correspond to. The tree hash can be viewed with git log --pretty="%T %s".
    4. Explain what each type of vote means
    5. Explain the conditions for the vote passing, including how long the vote will remain open for.
    6. Include a link to this wiki page so voters can read the instructions in it on how to test, verify, and vote. 
    7. Explain how you tested it.
    8. At your discretion, discuss what dependencies or tools you used to compile or run it, like gcc, and so on.

2. Release Phase

  1. If the vote passes, and Quickstep has yet to graduate, take a vote in the incubator PMC, following current incubator policy.

    1. Subscribe to general@incubator.apache.org by sending mail to general-subscribe@ and responding to the email it sends back.
    2. Send an email to that list including:
    3. Subject "[VOTE] quickstep x.y.z release candidate w"
    4. A link to the archive of the proposal thread from the dev@impala mailing list, available either mail-archives or apache-lists.
    5. A link to the archive of the [RESULT] of the vote from the dev@quickstep mailing list.
    6. A link to the artifacts for testing
    7. A link to the KEYS file with the signatures
    8. A link to the git tag the release candidate tarball was created from
    9. The tree hash of the git commit the release candidate tarball was created from
    10. Instructions on using RAT on our code, or a description of where to find that information.
    11. Build instructions, or a description of where to find that information.
    12. A list of the IPMC members who have already +1ed. For instance, as of 28 September 2016, all of our mentors are IPMC members, so their +1s are good for either vote - the one with the PPMC or the one with the IPMC.
    13. This vote will be open for at least 72 hours, or until the necessary
      number of votes (3 +1) is reached.
      
      [ ] +1 Approve the release
      [ ] -1 Don't approve the release (please provide specific comments)
  2. Like with the dev@ vote, post a "[RESULT]" thread to general@ with the results.

  3. Once that vote passes, tag the git tree at the release:

     

    git fetch apache
    git checkout apache/branch-x.y.z
    git tag -a x.y.z -m "x.y.z release"
    git push apache x.y.z
  4. Publish the release. While incubating, the location is this repo. Upload all four artifacts.

     

    svn checkout https://dist.apache.org/repos/dist/release/incubator/quickstep/
    cd quickstep/
    mkdir x.y.z
    cd x.y.z
    cp /tmp/apache-quickstep-incubating-x.y.z.tar.gz* ./
    svn add .
    svn commit --username=YOUR_APACHE_USER_NAME
    # You will be prompted to write a commit message. Make it look like (without the '#'s):
    #
    # Quickstep release x.y.z
    #
    # PPMC vote thread: ...
    #
    # PPMC vote results thread: ...
    #
    # IPMC vote thread: ...
    #
    # IPMC vote results thread: ...
  5. Wait 24 hours for mirrors to catch up.
  6. Push your patch to the downloads.html page.
  7. Announce the release to dev@quickstep.apache.org, user@quickstep.apache.org, and announce@apache.org. The email must come from your apache.org email address.
    1. If you are not already subscribed from your @apache.org address, subscribe to dev@ and user@ by mailing dev-subscribe@ and user-subscribe@.
    2. Give your email a subject like "[ANNOUNCE] Apache Quickstep (incubating) x.y.z release", and include in the body:

      The Apache Quickstep (incubating) team is pleased to announce the release of Quickstep x.y.z.
       
      Quickstep is a high-performance C++ SQL query engine.
       
      The release is available at: https://quickstep.incubator.apache.org/release
       
      Thanks,
       
      The Apache Quickstep (incubating) team
       
      =====
       
      *Disclaimer*
       
      Apache Quickstep is an effort undergoing incubation at The Apache Software Foundation (ASF),
      sponsored by the name of Apache Incubator PMC. Incubation is required of all newly accepted
      projects until a further review indicates that the infrastructure, communications, and
      decision making process have stabilized in a manner consistent with other successful ASF
      projects. While incubation status is not necessarily a reflection of the completeness or
      stability of the code, it does indicate that the project has yet to be fully endorsed by
      the ASF.

       

  8. Announce the release on the community links listed on https://quickstep.apache.org/community.html.
  9. Send a patch review to the master branch to update its version number to "p.q.r-SNAPSHOT" (where p.q.r is greater than x.y.z)
  10. In the bug tracker, change the target version for bugs targeted at x.y.z to p.q.r. You may need to create a version p.q.r if it does not already exist.

Related articles

How to Release - Impala's release guide which we liberally borrowed from.