Google Git
Sign in
apache / calcite-site / a7c0f0aad9ece6dc56d14a97a54db4f940bc6895 / . / avatica / docs / howto.html
blob: 5549a00ffcf7d393cb4230018623e2d0f1ac51ae [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<title>HOWTO</title>
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.7.3">
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="/avatica/css/screen.css">
<link rel="icon" type="image/x-icon" href="/avatica/favicon.ico">
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header role="banner">
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/avatica/">Home</a>
</li>
<li class="">
<a href="/avatica/downloads/">Download</a>
</li>
<li class="">
<a href="/avatica/community/">Community</a>
</li>
<li class="">
<a href="/avatica/develop/">Develop</a>
</li>
<li class="">
<a href="/avatica/news/">News</a>
</li>
<li class="current">
<a href="/avatica/docs/">Docs</a>
</li>
</ul>
</nav>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<h1>
<a href="/avatica/">
<span class="sr-only">Apache Calcite Avatica</span>
<img src="/avatica/img/logo.png" width="226" height="140" alt="Calcite Logo">
</a>
</h1>
</div>
<nav class="main-nav unit two-thirds hide-on-mobiles">
<ul>
<li class="">
<a href="/avatica/">Home</a>
</li>
<li class="">
<a href="/avatica/downloads/">Download</a>
</li>
<li class="">
<a href="/avatica/community/">Community</a>
</li>
<li class="">
<a href="/avatica/develop/">Develop</a>
</li>
<li class="">
<a href="/avatica/news/">News</a>
</li>
<li class="current">
<a href="/avatica/docs/">Docs</a>
</li>
</ul>
</nav>
</div>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Overview">
</optgroup>
<optgroup label="Avatica Reference">
</optgroup>
<optgroup label="Avatica Go Client Reference">
</optgroup>
<optgroup label="Avatica Meta">
</optgroup>
<optgroup label="Avatica Go Client Meta">
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<h1>HOWTO</h1>
<!--
-->
<p>Here’s some miscellaneous documentation about using Avatica.</p>
<ul id="markdown-toc">
<li><a href="#building-from-a-source-distribution" id="markdown-toc-building-from-a-source-distribution">Building from a source distribution</a></li>
<li><a href="#building-from-git" id="markdown-toc-building-from-git">Building from git</a></li>
<li><a href="#running-tests" id="markdown-toc-running-tests">Running tests</a> <ul>
<li><a href="#running-tests-in-your-environment" id="markdown-toc-running-tests-in-your-environment">Running tests in your environment</a></li>
<li><a href="#to-run-tests-in-docker" id="markdown-toc-to-run-tests-in-docker">To run tests in docker:</a></li>
</ul>
</li>
<li><a href="#contributing" id="markdown-toc-contributing">Contributing</a></li>
<li><a href="#getting-started" id="markdown-toc-getting-started">Getting started</a></li>
<li><a href="#advanced-topics-for-developers" id="markdown-toc-advanced-topics-for-developers">Advanced topics for developers</a></li>
<li><a href="#advanced-topics-for-committers" id="markdown-toc-advanced-topics-for-committers">Advanced topics for committers</a> <ul>
<li><a href="#set-up-pgp-signing-keys-for-calcite-committers" id="markdown-toc-set-up-pgp-signing-keys-for-calcite-committers">Set up PGP signing keys (for Calcite committers)</a></li>
<li><a href="#run-a-gpg-agent" id="markdown-toc-run-a-gpg-agent">Run a GPG agent</a></li>
<li><a href="#set-up-maven-repository-credentials-for-calcite-committers" id="markdown-toc-set-up-maven-repository-credentials-for-calcite-committers">Set up Maven repository credentials (for Calcite committers)</a></li>
<li><a href="#making-a-snapshot-for-calcite-committers" id="markdown-toc-making-a-snapshot-for-calcite-committers">Making a snapshot (for Calcite committers)</a></li>
<li><a href="#making-a-release-for-calcite-committers" id="markdown-toc-making-a-release-for-calcite-committers">Making a release (for Calcite committers)</a> <ul>
<li><a href="#to-perform-the-dry-run-directly-in-your-environment" id="markdown-toc-to-perform-the-dry-run-directly-in-your-environment">To perform the dry-run directly in your environment:</a></li>
<li><a href="#to-perform-the-dry-run-in-docker" id="markdown-toc-to-perform-the-dry-run-in-docker">To perform the dry-run in docker:</a></li>
<li><a href="#if-you-are-building-directly-in-your-environment" id="markdown-toc-if-you-are-building-directly-in-your-environment">If you are building directly in your environment:</a></li>
<li><a href="#if-you-are-building-using-docker" id="markdown-toc-if-you-are-building-using-docker">If you are building using docker:</a></li>
<li><a href="#to-build-directly-in-your-environment" id="markdown-toc-to-build-directly-in-your-environment">To build directly in your environment:</a></li>
<li><a href="#to-build-using-docker" id="markdown-toc-to-build-using-docker">To build using docker:</a></li>
<li><a href="#to-upload-the-artifacts-directly-in-your-environment" id="markdown-toc-to-upload-the-artifacts-directly-in-your-environment">To upload the artifacts directly in your environment:</a></li>
<li><a href="#to-upload-the-artifacts-using-docker" id="markdown-toc-to-upload-the-artifacts-using-docker">To upload the artifacts using docker:</a></li>
</ul>
</li>
<li><a href="#cleaning-up-after-a-failed-release-attempt-for-calcite-committers" id="markdown-toc-cleaning-up-after-a-failed-release-attempt-for-calcite-committers">Cleaning up after a failed release attempt (for Calcite committers)</a></li>
<li><a href="#validate-a-release" id="markdown-toc-validate-a-release">Validate a release</a></li>
<li><a href="#get-approval-for-a-release-via-apache-voting-process-for-calcite-committers" id="markdown-toc-get-approval-for-a-release-via-apache-voting-process-for-calcite-committers">Get approval for a release via Apache voting process (for Calcite committers)</a></li>
<li><a href="#publishing-a-release-for-calcite-committers" id="markdown-toc-publishing-a-release-for-calcite-committers">Publishing a release (for Calcite committers)</a> <ul>
<li><a href="#publishing-directly-in-your-environment" id="markdown-toc-publishing-directly-in-your-environment">Publishing directly in your environment:</a></li>
<li><a href="#publishing-a-release-using-docker" id="markdown-toc-publishing-a-release-using-docker">Publishing a release using docker:</a></li>
</ul>
</li>
<li><a href="#add-release-notes-and-announce-the-release" id="markdown-toc-add-release-notes-and-announce-the-release">Add release notes and announce the release</a></li>
<li><a href="#publish-the-web-site" id="markdown-toc-publish-the-web-site">Publishing the web site (for Calcite committers)</a></li>
</ul>
</li>
</ul>
<h2 id="building-from-a-source-distribution">Building from a source distribution</h2>
<p>Prerequisites are maven (3.2.1 or later)
and Java (JDK 8 or later) on your path.</p>
<p>Unpack the source distribution <code class="highlighter-rouge">.tar.gz</code> file,
<code class="highlighter-rouge">cd</code> to the root directory of the unpacked source,
then build using maven:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span><span class="nb">tar </span>xvfz apache-calcite-avatica-1.15.0-src.tar.gz
<span class="nv">$ </span><span class="nb">cd </span>apache-calcite-avatica-1.15.0-src
<span class="nv">$ </span>./mvnw install</code></pre></figure>
<p><a href="#running-tests">Running tests</a> describes how to run more or fewer
tests.</p>
<h2 id="building-from-git">Building from git</h2>
<p>Prerequisites are git, maven (3.2.1 or later)
and Java (JDK 8 or later) on your path.</p>
<p>Create a local copy of the github repository,
<code class="highlighter-rouge">cd</code> to its root directory,
then build using maven:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>git clone git://github.com/apache/calcite-avatica.git avatica
<span class="nv">$ </span><span class="nb">cd </span>avatica
<span class="nv">$ </span>./mvnw install</code></pre></figure>
<p><a href="#running-tests">Running tests</a> describes how to run more or fewer
tests.</p>
<h2 id="running-tests">Running tests</h2>
<p>The test suite will run by default when you build, unless you specify
<code class="highlighter-rouge">-DskipTests</code>.</p>
<h3 id="running-tests-in-your-environment">Running tests in your environment</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>./mvnw clean verify <span class="nt">-Dcheckstyle</span>.skip</code></pre></figure>
<p>By default, invoking the <code class="highlighter-rouge">verify</code> Maven lifecycle phase will also cause checkstyle
rules to be run. It is expected that contributions pass the checkstyle rules; however,
it is common to ignore these while working on a feature/bug and fix them at the end.</p>
<h3 id="to-run-tests-in-docker">To run tests in docker:</h3>
<ul>
<li>You will need to have <a href="https://docs.docker.com/install/">docker</a> and <a href="https://docs.docker.com/compose/install/">Docker Compose</a> installed.</li>
</ul>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">docker-compose run <span class="nb">test</span></code></pre></figure>
<h2 id="contributing">Contributing</h2>
<p>See the <a href="/avatica/develop/#contributing">developers guide</a>.</p>
<h2 id="getting-started">Getting started</h2>
<p>See the <a href="/avatica/develop/#getting-started">developers guide</a>.</p>
<h1 id="advanced-topics-for-developers">Advanced topics for developers</h1>
<p>The following sections might be of interest if you are adding features
to particular parts of the code base. You don’t need to understand
these topics if you are just building from source and running tests.</p>
<h1 id="advanced-topics-for-committers">Advanced topics for committers</h1>
<p>The following sections are of interest to Calcite committers and in
particular release managers.</p>
<h2 id="set-up-pgp-signing-keys-for-calcite-committers">Set up PGP signing keys (for Calcite committers)</h2>
<p>Follow instructions <a href="http://www.apache.org/dev/release-signing">here</a> to
create a key pair. (On Mac OS X, I did <code class="highlighter-rouge">brew install gpg</code> and
<code class="highlighter-rouge">gpg --gen-key</code>.)</p>
<p>Add your public key to the
<a href="https://dist.apache.org/repos/dist/release/calcite/KEYS"><code class="highlighter-rouge">KEYS</code></a>
file by following instructions in the <code class="highlighter-rouge">KEYS</code> file.
(The <code class="highlighter-rouge">KEYS</code> file is not present in the git repo or in a release tar
ball because that would be
<a href="https://issues.apache.org/jira/browse/CALCITE-1746">redundant</a>.)</p>
<h2 id="run-a-gpg-agent">Run a GPG agent</h2>
<p>By default, Maven plugins which require you to unlock a GPG secret key
will prompt you in the terminal. To prevent you from having to enter
this password numerous times, it is highly recommended to install and
run <code class="highlighter-rouge">gpg-agent</code>.</p>
<p>This can be started automatically via an <code class="highlighter-rouge">~/.xsession</code> on Linux or some
scripting in your shell’s configuration script of choice (e.g. <code class="highlighter-rouge">~/.bashrc</code> or <code class="highlighter-rouge">~/.zshrc</code>)</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">GPG_AGENT</span><span class="o">=</span><span class="k">$(</span>which gpg-agent<span class="k">)</span>
<span class="nv">GPG_TTY</span><span class="o">=</span><span class="sb">`</span>tty<span class="sb">`</span>
<span class="nb">export </span>GPG_TTY
<span class="k">if</span> <span class="o">[[</span> <span class="nt">-f</span> <span class="s2">"</span><span class="nv">$GPG_AGENT</span><span class="s2">"</span> <span class="o">]]</span><span class="p">;</span> <span class="k">then
</span><span class="nv">envfile</span><span class="o">=</span><span class="s2">"</span><span class="k">${</span><span class="nv">HOME</span><span class="k">}</span><span class="s2">/.gnupg/gpg-agent.env"</span>
<span class="k">if </span><span class="nb">test</span> <span class="nt">-f</span> <span class="s2">"</span><span class="nv">$envfile</span><span class="s2">"</span> <span class="o">&amp;&amp;</span> <span class="nb">kill</span> <span class="nt">-0</span> <span class="k">$(</span><span class="nb">grep </span>GPG_AGENT_INFO <span class="s2">"</span><span class="nv">$envfile</span><span class="s2">"</span> | cut <span class="nt">-d</span>: <span class="nt">-f</span> 2<span class="k">)</span> 2&gt;/dev/null<span class="p">;</span> <span class="k">then
</span><span class="nb">source</span> <span class="s2">"</span><span class="nv">$envfile</span><span class="s2">"</span>
<span class="k">else
</span><span class="nb">eval</span> <span class="s2">"</span><span class="k">$(</span>gpg-agent <span class="nt">--daemon</span> <span class="nt">--log-file</span><span class="o">=</span>~/.gpg/gpg.log <span class="nt">--write-env-file</span> <span class="s2">"</span><span class="nv">$envfile</span><span class="s2">"</span><span class="k">)</span><span class="s2">"</span>
<span class="k">fi
</span><span class="nb">export </span>GPG_AGENT_INFO <span class="c"># the env file does not contain the export statement</span>
<span class="k">fi</span></code></pre></figure>
<p>Also, ensure that <code class="highlighter-rouge">default-cache-ttl 6000</code> is set in <code class="highlighter-rouge">~/.gnupg/gpg-agent.conf</code>
to guarantee that your credentials will be cached for the duration of the build.</p>
<h2 id="set-up-maven-repository-credentials-for-calcite-committers">Set up Maven repository credentials (for Calcite committers)</h2>
<p>Follow the instructions <a href="http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env">here</a> to add your credentials to your maven configuration.</p>
<h2 id="making-a-snapshot-for-calcite-committers">Making a snapshot (for Calcite committers)</h2>
<p>Before you start:</p>
<ul>
<li>Set up signing keys as described above.</li>
<li>Make sure you are using JDK 8 (not 9 or 10).</li>
</ul>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Make sure that there are no junk files in the sandbox</span>
git clean <span class="nt">-xn</span>
./mvnw <span class="nt">-Papache-release</span> clean install</code></pre></figure>
<p>When the dry-run has succeeded, change <code class="highlighter-rouge">install</code> to <code class="highlighter-rouge">deploy</code>.</p>
<h2 id="making-a-release-for-calcite-committers">Making a release (for Calcite committers)</h2>
<p>Before you start:</p>
<ul>
<li>Set up signing keys as described above.</li>
<li>Make sure you are using JDK 8 (not 9 or 10).</li>
<li>Check that <code class="highlighter-rouge">README</code>, <code class="highlighter-rouge">site/_docs/howto.md</code>, <code class="highlighter-rouge">site/_docs/docker_images.md</code> have the correct version number.</li>
<li>Check that <code class="highlighter-rouge">NOTICE</code> has the current copyright year.</li>
<li>Set <code class="highlighter-rouge">version.major</code> and <code class="highlighter-rouge">version.minor</code> in <code class="highlighter-rouge">pom.xml</code>.</li>
<li>Add release notes to <code class="highlighter-rouge">site/_docs/history.md</code>. Include the commit history,
and say which versions of Java, Guava and operating systems the release is
tested against.</li>
<li>Generate a report of vulnerabilities that occur among dependencies,
using <code class="highlighter-rouge">./mvnw verify -Ppedantic</code>.</li>
<li>Make sure that
<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20AND%20status%20%3D%20Resolved%20and%20fixVersion%20is%20null">
every “resolved” JIRA case</a> (including duplicates) has
a fix version assigned (most likely the version we are
just about to release)</li>
</ul>
<p>Create a release branch named after the release, e.g.
<code class="highlighter-rouge">branch-avatica-1.9</code>, and push it to Apache.</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>git checkout <span class="nt">-b</span> branch-avatica-X.Y
<span class="nv">$ </span>git push <span class="nt">-u</span> origin branch-avatica-X.Y</code></pre></figure>
<p>We will use the branch for the entire the release process. Meanwhile,
we do not allow commits to the master branch. After the release is
final, we can use <code class="highlighter-rouge">git merge --ff-only</code> to append the changes on the
release branch onto the master branch. (Apache does not allow reverts
to the master branch, which makes it difficult to clean up the kind of
messy commits that inevitably happen while you are trying to finalize
a release.)</p>
<p>Now, set up your environment and do a dry run. The dry run will not
commit any changes back to git and gives you the opportunity to verify
that the release process will complete as expected.</p>
<p>If any of the steps fail, clean up (see below), fix the problem, and
start again from the top.</p>
<p>To perform the dry-run, you can either use your environment or the release script and docker.</p>
<h3 id="to-perform-the-dry-run-directly-in-your-environment">To perform the dry-run directly in your environment:</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Make sure that there are no junk files in the sandbox</span>
git clean <span class="nt">-xn</span>
<span class="c"># Do a dry run of the release:prepare step, which sets version numbers.</span>
<span class="c"># Typically we increment minor version: If X.Y.Z is 1.15.0, X2.Y2.Z2 is 1.16.0.</span>
<span class="c"># Note X.Y.Z is the current version we're trying to release, and X2.Y2.Z2 is the next development version.</span>
<span class="c"># For example, if I am currently building a release for 1.15.0, X.Y.Z would be 1.15.0 and X2.Y2.Z2 would be 1.16.0.</span>
./mvnw <span class="nt">-DdryRun</span><span class="o">=</span><span class="nb">true</span> <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span> <span class="nt">-Duser</span>.name<span class="o">=</span><span class="k">${</span><span class="nv">asf</span><span class="p">.username</span><span class="k">}</span> release:prepare
<span class="c"># If you have multiple GPG keys, you can select the key used to sign the release by appending `-Dgpg.keyname=${your.key.id}` to `-Darguments`:</span>
./mvnw <span class="nt">-DdryRun</span><span class="o">=</span><span class="nb">true</span> <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span> <span class="nt">-Duser</span>.name<span class="o">=</span><span class="k">${</span><span class="nv">asf</span><span class="p">.username</span><span class="k">}</span> release:prepare <span class="nt">-Darguments</span><span class="o">=</span><span class="nt">-Dgpg</span>.keyname<span class="o">=</span><span class="k">${</span><span class="nv">your</span><span class="p">.key.id</span><span class="k">}</span></code></pre></figure>
<h3 id="to-perform-the-dry-run-in-docker">To perform the dry-run in docker:</h3>
<ul>
<li>
<p>You will need to have <a href="https://docs.docker.com/install/">docker</a> and <a href="https://docs.docker.com/compose/install/">Docker Compose</a> installed.</p>
</li>
<li>
<p>The script expects you to mount your <code class="highlighter-rouge">~/.gnupg</code> directory into the <code class="highlighter-rouge">/.gnupg</code> directory in the container. Once mounted into the container,
the script will make a copy of the contents and move it to a different location, so that it will not modify the contents of your original
<code class="highlighter-rouge">~/.gnupg</code> directory during the build.</p>
</li>
</ul>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># On Linux:</span>
docker-compose run <span class="nt">-v</span> ~/.gnupg:/.gnupg dry-run
<span class="c"># On Windows</span>
docker-compose run <span class="nt">-v</span> /c/Users/username/AppData/Roaming/gnupg:/.gnupg dry-run</code></pre></figure>
<p>Check the artifacts:</p>
<ul>
<li>In the <code class="highlighter-rouge">target</code> directory should be these 4 files, among others:
<ul>
<li>apache-calcite-avatica-X.Y.Z-src.tar.gz</li>
<li>apache-calcite-avatica-X.Y.Z-src.tar.gz.asc</li>
<li>apache-calcite-avatica-X.Y.Z-src.tar.gz.asc.sha512</li>
<li>apache-calcite-avatica-X.Y.Z-src.tar.gz.sha512</li>
</ul>
</li>
<li>Note that the file names start <code class="highlighter-rouge">apache-calcite-avatica-</code>.</li>
<li>In the source distro <code class="highlighter-rouge">.tar.gz</code> (currently there is
no binary distro), check that all files belong to a directory called
<code class="highlighter-rouge">apache-calcite-avatica-X.Y.Z-src</code>.</li>
<li>That directory must contain files <code class="highlighter-rouge">NOTICE</code>, <code class="highlighter-rouge">LICENSE</code>,
<code class="highlighter-rouge">README</code>, <code class="highlighter-rouge">README.md</code>
<ul>
<li>Check that the version in <code class="highlighter-rouge">README</code> is correct</li>
</ul>
</li>
<li>Make sure that there is no <code class="highlighter-rouge">KEYS</code> file in the source distros</li>
<li>For each .jar (for example <code class="highlighter-rouge">core/target/avatica-core-X.Y.Z.jar</code>
and <code class="highlighter-rouge">server/target/avatica-server-X.Y.Z-sources.jar</code>),
verify that the <code class="highlighter-rouge">META-INF</code> directory contains the correct
contents for <code class="highlighter-rouge">DEPENDENCIES</code>, <code class="highlighter-rouge">LICENSE</code> and <code class="highlighter-rouge">NOTICE</code> per the
source/classes contained. Refer to the ASF licensing documentation on
what is required.</li>
<li>Check PGP, per <a href="https://httpd.apache.org/dev/verification.html">this</a></li>
</ul>
<p>If something is not correct, you can invoke the <code class="highlighter-rouge">release:clean</code> mojo to remove the
generated files from your workspace:</p>
<h3 id="if-you-are-building-directly-in-your-environment">If you are building directly in your environment:</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">./mvnw release:clean</code></pre></figure>
<h3 id="if-you-are-building-using-docker">If you are building using docker:</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">docker-compose run clean</code></pre></figure>
<p>If successful, remove the <code class="highlighter-rouge">-DdryRun</code> flag and run the release for real.</p>
<h3 id="to-build-directly-in-your-environment">To build directly in your environment:</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Prepare sets the version numbers, creates a tag, and pushes it to git.</span>
<span class="c"># Typically we increment minor version: If X.Y.Z is 1.15.0, X2.Y2.Z2 is 1.16.0.</span>
<span class="c"># Note X.Y.Z is the current version we're trying to release, and X2.Y2.Z2 is the next development version.</span>
<span class="c"># For example, if I am currently building a release for 1.15.0, X.Y.Z would be 1.15.0 and X2.Y2.Z2 would be 1.16.0.</span>
./mvnw <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span> <span class="nt">-Duser</span>.name<span class="o">=</span><span class="k">${</span><span class="nv">asf</span><span class="p">.username</span><span class="k">}</span> release:prepare
<span class="c"># If you have multiple GPG keys, you can select the key used to sign the release by appending `-Darguments=-Dgpg.keyname=${your.key.id}`:</span>
./mvnw <span class="nt">-DreleaseVersion</span><span class="o">=</span>X.Y.Z <span class="nt">-DdevelopmentVersion</span><span class="o">=</span>X2.Y2.Z2-SNAPSHOT <span class="nt">-Dtag</span><span class="o">=</span>avatica-X.Y.Z-rcN <span class="nt">-Papache-release</span> <span class="nt">-Duser</span>.name<span class="o">=</span><span class="k">${</span><span class="nv">asf</span><span class="p">.username</span><span class="k">}</span> release:prepare <span class="nt">-Darguments</span><span class="o">=</span><span class="nt">-Dgpg</span>.keyname<span class="o">=</span><span class="k">${</span><span class="nv">your</span><span class="p">.key.id</span><span class="k">}</span>
<span class="c"># Perform checks out the tagged version, builds, and deploys to the staging repository</span>
./mvnw <span class="nt">-Papache-release</span> <span class="nt">-Duser</span>.name<span class="o">=</span><span class="k">${</span><span class="nv">asf</span><span class="p">.username</span><span class="k">}</span> release:perform <span class="nt">-Darguments</span><span class="o">=</span><span class="s2">"-DskipTests"</span></code></pre></figure>
<h3 id="to-build-using-docker">To build using docker:</h3>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># On Linux:</span>
docker-compose run <span class="nt">-v</span> ~/.gnupg:/.gnupg release
<span class="c"># On Windows</span>
docker-compose run <span class="nt">-v</span> /c/Users/username/AppData/Roaming/gnupg:/.gnupg release</code></pre></figure>
<p>Verify the staged artifacts in the Nexus repository:</p>
<ul>
<li>Go to <a href="https://repository.apache.org/">https://repository.apache.org/</a> and login</li>
<li>Under <code class="highlighter-rouge">Build Promotion</code>, click <code class="highlighter-rouge">Staging Repositories</code></li>
<li>In the <code class="highlighter-rouge">Staging Repositories</code> tab there should be a line with profile <code class="highlighter-rouge">org.apache.calcite</code></li>
<li>Navigate through the artifact tree and make sure the .jar, .pom, .asc files are present</li>
<li>Check the box on in the first column of the row,
and press the ‘Close’ button to publish the repository at
https://repository.apache.org/content/repositories/orgapachecalcite-1000
(or a similar URL)</li>
</ul>
<h3 id="to-upload-the-artifacts-directly-in-your-environment">To upload the artifacts directly in your environment:</h3>
<p>Upload the artifacts via subversion to a staging area,
https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Create a subversion workspace, if you haven't already</span>
mkdir <span class="nt">-p</span> ~/dist/dev
<span class="nb">pushd</span> ~/dist/dev
svn co https://dist.apache.org/repos/dist/dev/calcite
<span class="nb">popd</span>
<span class="c"># Move the files into a directory</span>
<span class="nb">cd </span>target
mkdir ~/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN
mv apache-calcite-avatica-<span class="k">*</span> ~/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN
<span class="c"># Check in</span>
<span class="nb">cd</span> ~/dist/dev/calcite
svn add apache-calcite-avatica-X.Y.Z-rcN
svn ci</code></pre></figure>
<h3 id="to-upload-the-artifacts-using-docker">To upload the artifacts using docker:</h3>
<p>This assumes that a release was built and the artifacts are in the <code class="highlighter-rouge">target</code> folder.</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">docker-compose run publish-release-for-voting</code></pre></figure>
<p>The automated process also generates a vote email that can be sent to the list. Please check the email and amend the
contents as necessary.</p>
<h2 id="cleaning-up-after-a-failed-release-attempt-for-calcite-committers">Cleaning up after a failed release attempt (for Calcite committers)</h2>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Make sure that the tag you are about to generate does not already</span>
<span class="c"># exist (due to a failed release attempt)</span>
git tag
<span class="c"># If the tag exists, delete it locally and remotely</span>
git tag <span class="nt">-d</span> avatica-X.Y.Z
git push origin :refs/tags/avatica-X.Y.Z
<span class="c"># Remove modified files</span>
./mvnw release:clean
<span class="c"># Check whether there are modified files and if so, go back to the</span>
<span class="c"># original git commit</span>
git status
git reset <span class="nt">--hard</span> HEAD</code></pre></figure>
<h2 id="validate-a-release">Validate a release</h2>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Check that the signing key (e.g. 2AD3FAE3) is pushed</span>
gpg <span class="nt">--recv-keys</span> key
<span class="c"># Check keys</span>
curl <span class="nt">-O</span> https://dist.apache.org/repos/dist/release/calcite/KEYS
<span class="c"># Sign/check sha256 hashes</span>
<span class="c"># (Assumes your O/S has a 'shasum' command.)</span>
<span class="k">function </span>checkHash<span class="o">()</span> <span class="o">{</span>
<span class="nb">cd</span> <span class="s2">"</span><span class="nv">$1</span><span class="s2">"</span>
<span class="k">for </span>i <span class="k">in</span> <span class="k">*</span>.<span class="o">{</span>pom,gz<span class="o">}</span><span class="p">;</span> <span class="k">do
if</span> <span class="o">[</span> <span class="o">!</span> <span class="nt">-f</span> <span class="nv">$i</span> <span class="o">]</span><span class="p">;</span> <span class="k">then
continue
fi
if</span> <span class="o">[</span> <span class="nt">-f</span> <span class="nv">$i</span>.sha256 <span class="o">]</span><span class="p">;</span> <span class="k">then
if</span> <span class="o">[</span> <span class="s2">"</span><span class="k">$(</span><span class="nb">cat</span> <span class="nv">$i</span>.sha256<span class="k">)</span><span class="s2">"</span> <span class="o">=</span> <span class="s2">"</span><span class="k">$(</span>shasum <span class="nt">-a</span> 256 <span class="nv">$i</span><span class="k">)</span><span class="s2">"</span> <span class="o">]</span><span class="p">;</span> <span class="k">then
</span><span class="nb">echo</span> <span class="nv">$i</span>.sha256 present and correct
<span class="k">else
</span><span class="nb">echo</span> <span class="nv">$i</span>.sha256 does not match
<span class="k">fi
else
</span>shasum <span class="nt">-a</span> 256 <span class="nv">$i</span> <span class="o">&gt;</span> <span class="nv">$i</span>.sha256
<span class="nb">echo</span> <span class="nv">$i</span>.sha256 created
<span class="k">fi
done</span>
<span class="o">}</span>
checkHash apache-calcite-avatica-X.Y.Z-rcN</code></pre></figure>
<h2 id="get-approval-for-a-release-via-apache-voting-process-for-calcite-committers">Get approval for a release via Apache voting process (for Calcite committers)</h2>
<p>Release vote on dev list</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text">To: dev@calcite.apache.org
Subject: [VOTE] Release apache-calcite-avatica-X.Y.Z (release candidate N)
Hi all,
I have created a build for Apache Calcite Avatica X.Y.Z, release candidate N.
Thanks to everyone who has contributed to this release.
&lt;Further details about release.&gt; You can read the release notes here:
https://github.com/apache/calcite-avatica/blob/XXXX/site/_docs/history.md
The commit to be voted upon:
https://gitbox.apache.org/repos/asf/calcite-avatica/commit/NNNNNN
Its hash is XXXX.
The artifacts to be voted on are located here:
https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-avatica-X.Y.Z-rcN/
The hashes of the artifacts are as follows:
src.tar.gz.sha256 XXXX
A staged Maven repository is available for review at:
https://repository.apache.org/content/repositories/orgapachecalcite-NNNN
Release artifacts are signed with the following key:
https://people.apache.org/keys/committer/jhyde.asc
Please vote on releasing this package as Apache Calcite Avatica X.Y.Z.
The vote is open for the next 72 hours and passes if a majority of
at least three +1 PMC votes are cast.
[ ] +1 Release this package as Apache Calcite X.Y.Z
[ ] 0 I don't feel strongly about it, but I'm okay with the release
[ ] -1 Do not release this package because...
Here is my vote:
+1 (binding)
Julian</code></pre></figure>
<p>After vote finishes, send out the result:</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text">Subject: [RESULT] [VOTE] Release apache-calcite-avatica-X.Y.Z (release candidate N)
To: dev@calcite.apache.org
Thanks to everyone who has tested the release candidate and given
their comments and votes.
The tally is as follows.
N binding +1s:
&lt;names&gt;
N non-binding +1s:
&lt;names&gt;
No 0s or -1s.
Therefore I am delighted to announce that the proposal to release
Apache Calcite Avatica X.Y.Z has passed.
Thanks everyone. We’ll now roll the release out to the mirrors.
There was some feedback during voting. I shall open a separate
thread to discuss.
Julian</code></pre></figure>
<p>Use the <a href="http://s.apache.org">Apache URL shortener</a> to generate
shortened URLs for the vote proposal and result emails. Examples:
<a href="http://s.apache.org/calcite-1.2-vote">s.apache.org/calcite-1.2-vote</a> and
<a href="http://s.apache.org/calcite-1.2-result">s.apache.org/calcite-1.2-result</a>.</p>
<h2 id="publishing-a-release-for-calcite-committers">Publishing a release (for Calcite committers)</h2>
<p>After a successful release vote, we need to push the release
out to mirrors, and other tasks.</p>
<p>Choose a release date.
This is based on the time when you expect to announce the release.
This is usually a day after the vote closes.
Remember that UTC date changes at 4pm Pacific time.</p>
<p>In JIRA, search for
<a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20and%20fixVersion%20%3D%201.5.0%20and%20status%20%3D%20Resolved%20and%20resolution%20%3D%20Fixed">all issues resolved in this release</a>,
and do a bulk update changing their status to “Closed”,
with a change comment
“Resolved in release X.Y.Z (YYYY-MM-DD)”
(fill in release number and date appropriately).
Uncheck “Send mail for this update”.</p>
<p>Promote the staged nexus artifacts.</p>
<ul>
<li>Go to <a href="https://repository.apache.org/">https://repository.apache.org/</a> and login</li>
<li>Under “Build Promotion” click “Staging Repositories”</li>
<li>In the line with “orgapachecalcite-xxxx”, check the box</li>
<li>Press “Release” button</li>
</ul>
<p>Tip: Push the git tag only after the staged nexus artifacts are promoted in the repository. This is because pushing the
tag triggers Docker Hub to start building the docker images immediately and the build will pull in the promoted artifacts.
If the artifacts are not yet available, the build on Docker Hub will fail. It’s best to continue with the following steps
after you have confirmed that the nexus artifacts were promoted properly.</p>
<h3 id="publishing-directly-in-your-environment">Publishing directly in your environment:</h3>
<p>Copy the Git tag:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git tag rel/avatica-X.Y.X avatica-X.Y.Z-rcN
git push origin rel/avatica-X.Y.Z</code></pre></figure>
<p>Check the artifacts into svn.</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="c"># Get the release candidate.</span>
mkdir <span class="nt">-p</span> ~/dist/dev
<span class="nb">cd</span> ~/dist/dev
svn co https://dist.apache.org/repos/dist/dev/calcite
<span class="c"># Copy the artifacts. Note that the copy does not have '-rcN' suffix.</span>
mkdir <span class="nt">-p</span> ~/dist/release
<span class="nb">cd</span> ~/dist/release
svn co https://dist.apache.org/repos/dist/release/calcite
<span class="nb">cd </span>calcite
cp <span class="nt">-rp</span> ../../dev/calcite/apache-calcite-avatica-X.Y.Z-rcN apache-calcite-avatica-X.Y.Z
svn add apache-calcite-avatica-X.Y.Z
<span class="c"># Check in.</span>
svn ci</code></pre></figure>
<p>Svnpubsub will publish to the
<a href="https://dist.apache.org/repos/dist/release/calcite">release repo</a> and propagate to the
<a href="http://www.apache.org/dyn/closer.cgi/calcite">mirrors</a> within 24 hours.</p>
<p>If there are now more than 2 releases, clear out the oldest ones:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nb">cd</span> ~/dist/release/calcite
svn rm apache-calcite-avatica-X.Y.Z
svn ci</code></pre></figure>
<p>The old releases will remain available in the
<a href="http://archive.apache.org/dist/calcite/">release archive</a>.</p>
<p>Merge the release branch back to master and push it:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git checkout master
git merge branch-X.Y <span class="nt">--ff-only</span>
git push origin master</code></pre></figure>
<h3 id="publishing-a-release-using-docker">Publishing a release using docker:</h3>
<p>This assumes that a rc release was tagged and pushed to the git repository.</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">docker-compose run promote-release</code></pre></figure>
<h2 id="add-release-notes-and-announce-the-release">Add release notes and announce the release</h2>
<p>Add a release note by copying
<a href="https://github.com/apache/calcite-avatica/tree/master/site/_posts/2016-11-01-release-1.9.0.md">site/_posts/2016-11-01-release-1.9.0.md</a>,
generate the javadoc and copy to <code class="highlighter-rouge">site/target/avatica/apidocs</code>
and <code class="highlighter-rouge">site/target/avatica/testapidocs</code>,
<a href="#publish-the-web-site">publish the site</a>,
and check that it appears in the contents in <a href="http://localhost:4000/news/">news</a>.</p>
<p>After 24 hours, announce the release by sending an email to
<a href="https://mail-archives.apache.org/mod_mbox/www-announce/">announce@apache.org</a>.
You can use
<a href="https://mail-archives.apache.org/mod_mbox/www-announce/201606.mbox/%3C57559CC7.1000402@apache.org%3E">the 1.8.0 announcement</a>
as a template. Be sure to include a brief description of the project.</p>
<h2 id="publish-the-web-site">Publishing the web site (for Calcite committers)</h2>
<p>See instructions in
<a href="https://github.com/apache/calcite-avatica/tree/master/site/README.md">site/README.md</a>.</p>
<div class="section-nav">
<div class="left align-right">
<a href="/avatica/docs/protobuf_reference.html" class="prev">Previous</a>
</div>
<div class="right align-left">
<a href="/avatica/docs/security.html" class="next">Next</a>
</div>
</div>
<div class="clear"></div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Overview</h4>
<ul>
<li class=""><a href="/avatica/docs/index.html">Background</a></li>
<li class=""><a href="/avatica/docs/roadmap.html">Roadmap</a></li>
</ul>
<h4>Avatica Reference</h4>
<ul>
<li class=""><a href="/avatica/docs/client_reference.html">Client Reference</a></li>
<li class=""><a href="/avatica/docs/json_reference.html">JSON Reference</a></li>
<li class=""><a href="/avatica/docs/protobuf_reference.html">Protobuf Reference</a></li>
<li class="current"><a href="/avatica/docs/howto.html">HOWTO</a></li>
<li class=""><a href="/avatica/docs/security.html">Security</a></li>
<li class=""><a href="/avatica/docs/compatibility.html">Compatibility</a></li>
<li class=""><a href="/avatica/docs/custom_client_artifacts.html">Custom Client Artifacts</a></li>
<li class=""><a href="/avatica/docs/docker.html">Docker Images</a></li>
<li class=""><a href="/avatica/docs/protocol_testing.html">Protocol Testing</a></li>
</ul>
<h4>Avatica Go Client Reference</h4>
<ul>
<li class=""><a href="/avatica/docs/go_client_reference.html">Go Client Reference</a></li>
<li class=""><a href="/avatica/docs/go_howto.html">HOWTO</a></li>
</ul>
<h4>Avatica Meta</h4>
<ul>
<li class=""><a href="/avatica/docs/history.html">History</a></li>
<li class=""><a href="/avatica/docs/api/">API</a></li>
<li class=""><a href="/avatica/docs/testapi/">Test API</a></li>
</ul>
<h4>Avatica Go Client Meta</h4>
<ul>
<li class=""><a href="/avatica/docs/go_history.html">Go Client History</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer role="contentinfo">
<div id="poweredby">
<a href="http://www.apache.org/">
<span class="sr-only">Apache</span>
<img src="/avatica/img/feather.png" width="190" height="77" alt="Apache Logo"></a>
</div>
<div id="copyright">
<p>The contents of this website are &copy;&nbsp;2019
<a href="https://www.apache.org/">Apache Software Foundation</a>
under the terms of
the <a href="https://www.apache.org/licenses/LICENSE-2.0.html">
Apache&nbsp;License&nbsp;v2</a>. Apache Calcite and its logo are
trademarks of the Apache Software Foundation.</p>
</div>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
</body>
</html>