blob: 938b8a05ad217cf3562a22202f893fa028a5bb27 [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 v4.2.2">
<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">
</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="#releasing" id="markdown-toc-releasing">Releasing</a> <ul>
<li><a href="#preparing-for-release" id="markdown-toc-preparing-for-release">Preparing for release</a></li>
<li><a href="#perform-a-dry-run" id="markdown-toc-perform-a-dry-run">Perform a dry-run</a></li>
<li><a href="#build-the-release" id="markdown-toc-build-the-release">Build the release</a></li>
<li><a href="#check-the-release-before-uploading" id="markdown-toc-check-the-release-before-uploading">Check the release before uploading</a></li>
<li><a href="#uploading-release-artifacts-to-dev-for-voting" id="markdown-toc-uploading-release-artifacts-to-dev-for-voting">Uploading release artifacts to dev for voting</a> <ul>
<li><a href="#manually" id="markdown-toc-manually">Manually</a></li>
<li><a href="#using-docker" id="markdown-toc-using-docker">Using docker</a></li>
</ul>
</li>
<li><a href="#send-an-email-to-the-dev-list-for-voting" id="markdown-toc-send-an-email-to-the-dev-list-for-voting">Send an email to the Dev list for voting:</a></li>
<li><a href="#promoting-a-release-after-voting" id="markdown-toc-promoting-a-release-after-voting">Promoting a release after voting</a> <ul>
<li><a href="#manually-1" id="markdown-toc-manually-1">Manually</a></li>
<li><a href="#using-docker-1" id="markdown-toc-using-docker-1">Using docker</a></li>
</ul>
</li>
<li><a href="#close-out-issues-in-jira-and-mark-the-version-as-released" id="markdown-toc-close-out-issues-in-jira-and-mark-the-version-as-released">Close out issues in JIRA and mark the version as released</a></li>
<li><a href="#announce-the-release" id="markdown-toc-announce-the-release">Announce the release</a></li>
</ul>
</li>
</ul>
<h2 id="releasing">Releasing</h2>
<h3 id="preparing-for-release">Preparing for release</h3>
<ol>
<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>If you have not set up a GPG signing key, set one up by following these <a href="https://www.apache.org/dev/openpgp.html#generate-key">instructions</a>.</p>
</li>
<li>
<p>If this release is a new major version (we are releasing 4.0.0 vs the current version 3.0.0), update the version in the
import path in <code class="language-plaintext highlighter-rouge">go.mod</code>. The import paths in the various sample code snippets should also be updated.</p>
</li>
<li>
<p>Since we need to support Go modules, tags must be prefixed with a <code class="language-plaintext highlighter-rouge">v</code>. For example, tag as <code class="language-plaintext highlighter-rouge">v3.1.0</code> rather than <code class="language-plaintext highlighter-rouge">3.1.0</code>.</p>
</li>
<li>
<p>Check that <code class="language-plaintext highlighter-rouge">NOTICE</code> has the current copyright year.</p>
</li>
</ol>
<h3 id="perform-a-dry-run">Perform a dry-run</h3>
<ul>
<li>The script expects you to mount your <code class="language-plaintext highlighter-rouge">~/.gnupg</code> directory into the <code class="language-plaintext 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="language-plaintext highlighter-rouge">~/.gnupg</code> directory during the build.</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>
<h3 id="build-the-release">Build the release</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>If the build fails, perform a clean:</p>
<ol>
<li>Remove the git tag locally and remotely:</li>
</ol>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git tag <span class="nt">-d</span> vX.Y.Z-rcA
git push origin :refs/tags/vX.Y.Z-rcA</code></pre></figure>
<ol>
<li>Clean the local repository</li>
</ol>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">docker compose run clean</code></pre></figure>
<h3 id="check-the-release-before-uploading">Check the release before uploading</h3>
<p>The name of the release folder must be in the following format: <code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-rcN</code>. The version must
include release candidate identifiers such as <code class="language-plaintext highlighter-rouge">-rc0</code>, if they are present.</p>
<p>The files inside the release folder must have any release candidate identifiers such as <code class="language-plaintext highlighter-rouge">-rc1</code> removed, even if the
release is a release candidate. <code class="language-plaintext highlighter-rouge">src</code> must also be added to the filename.</p>
<p>For example, if we are uploading the <code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-3.0.0-rc1</code> folder, the files must be named
<code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-3.0.0-src.tar.gz</code>. Note the inclusion of <code class="language-plaintext highlighter-rouge">src</code> in the filename.</p>
<p>The tar.gz must be named <code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-src.tar.gz</code>.</p>
<p>There must be a GPG signature for the tar.gz named: <code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-src.tar.gz.asc</code></p>
<p>There must be a SHA512 hash for the tar.gz named: <code class="language-plaintext highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-src.tar.gz.sha512</code></p>
<h3 id="uploading-release-artifacts-to-dev-for-voting">Uploading release artifacts to dev for voting</h3>
<h4 id="manually">Manually</h4>
<p><code class="language-plaintext highlighter-rouge">svn</code> must be installed in order to upload release artifacts.</p>
<ol>
<li>
<p>Check out the Calcite dev release subdirectory: <code class="language-plaintext highlighter-rouge">svn co "https://dist.apache.org/repos/dist/dev/calcite/" calcite-dev</code>.</p>
</li>
<li>
<p>Move the release folder under <code class="language-plaintext highlighter-rouge">dist/</code> into the <code class="language-plaintext highlighter-rouge">calcite-dev</code> folder.</p>
</li>
<li>
<p>Add the new release to the svn repository: <code class="language-plaintext highlighter-rouge">svn add apache-calcite-avatica-go-X.Y.Z-rcN</code>. Remember to change the folder name to the
correct release in the command.</p>
</li>
<li>
<p>Commit to upload the artifacts: <code class="language-plaintext highlighter-rouge">svn commit -m "apache-calcite-avatica-go-X.Y.Z-rcN" --username yourapacheusername --force-log</code>
Note the use of <code class="language-plaintext highlighter-rouge">--force-log</code> to suppress the svn warning, because the commit message is the same as the name of the directory.</p>
</li>
</ol>
<h4 id="using-docker">Using docker</h4>
<p>This assumes that a release was built and the artifacts are in the <code class="language-plaintext highlighter-rouge">dist/</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 script will also generate a vote email to send to the dev list. You can use this email, but make sure to check that
all the details are correct.</p>
<h3 id="send-an-email-to-the-dev-list-for-voting">Send an email to the Dev list for voting:</h3>
<p>Send out the email for voting:</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text">
To: dev@calcite.apache.org
Subject: [VOTE] Release apache-calcite-avatica-go-X.Y.Z (release candidate N)
Hi all,
I have created a build for Apache Calcite Avatica Go X.Y.Z, release candidate N.
Thanks to everyone who has contributed to this release. The release notes are available here:
https://github.com/apache/calcite-avatica-go/blob/XXXX/site/_docs/go_history.md
The commit to be voted upon:
https://gitbox.apache.org/repos/asf?p=calcite-avatica-go.git;a=commit;h=NNNNNN
The hash is XXXX.
The artifacts to be voted on are located here:
https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-avatica-go-X.Y.Z-rcN/
The hashes of the artifacts are as follows:
src.tar.gz.sha512 XXXX
Release artifacts are signed with the following key:
https://people.apache.org/keys/committer/francischuang.asc
Instructions for running the test suite is located here:
https://github.com/apache/calcite-avatica-go/blob/$COMMIT/site/develop/avatica-go.md#testing
Please vote on releasing this package as Apache Calcite Avatica Go X.Y.Z.
To run the tests without a Go environment, install docker and docker compose. Then, in the root of the release's directory, run:
docker compose run test
When the test suite completes, run \"docker compose down\" to remove and shutdown all the containers.
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 Go 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)
Francis</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-go-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 Go X.Y.Z has passed.
Thanks everyone. We’ll now roll the release out to the mirrors.
Francis</code></pre></figure>
<h3 id="promoting-a-release-after-voting">Promoting a release after voting</h3>
<h4 id="manually-1">Manually</h4>
<p><code class="language-plaintext highlighter-rouge">svn</code> must be installed in order to upload release artifacts.</p>
<p>NOTE: Only official releases that has passed a vote may be uploaded to the release directory.</p>
<ol>
<li>
<p>Check out the Calcite release directory: <code class="language-plaintext highlighter-rouge">svn co "https://dist.apache.org/repos/dist/release/calcite/" calcite-release</code>.</p>
</li>
<li>
<p>Copy the release into the <code class="language-plaintext highlighter-rouge">calcite-release</code> folder. Remember to check the name of the release’s folder to ensure that it is in
the correct format.</p>
</li>
<li>
<p>Add the release to the svn repository: <code class="language-plaintext highlighter-rouge">svn add apache-calcite-avatica-go-X.Y.Z</code>. Remember to change the folder name to the
correct release in the command.</p>
</li>
<li>
<p>Commit to upload the artifacts: <code class="language-plaintext highlighter-rouge">svn commit -m "Release apache-calcite-avatica-go-X.Y.Z" --username yourapacheusername</code>.</p>
</li>
<li>
<p>Tag the final release in git and push it:</p>
</li>
</ol>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git tag vX.Y.Z X.Y.Z-rcN
git push origin vX.Y.Z</code></pre></figure>
<h4 id="using-docker-1">Using docker</h4>
<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>
<h3 id="close-out-issues-in-jira-and-mark-the-version-as-released">Close out issues in JIRA and mark the version as released</h3>
<p>In JIRA, search for <a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CALCITE%20AND%20status%20%3D%20Resolved%20AND%20resolution%20%3D%20Fixed%20AND%20fixVersion%20in%20(1.5.0%2C%20avatica-go-5.2.0)">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>Finally, go to the <a href="https://issues.apache.org/jira/projects/CALCITE?selectedItem=com.atlassian.jira.jira-projects-plugin%3Arelease-page&amp;status=released-unreleased">releases page in JIRA</a>,
click the 3 dots next to the release, select the release date and release it.</p>
<h3 id="announce-the-release">Announce the release</h3>
<p>After 24 hours, announce the release by sending an announcement to the <a href="https://mail-archives.apache.org/mod_mbox/calcite-dev/">dev list</a>
and <a href="https://mail-archives.apache.org/mod_mbox/www-announce/">announce@apache.org</a>.</p>
<p>An example of the announcement could look like:</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text">Subject: [ANNOUNCE] Apache Calcite Avatica Go X.Y.Z released
To: dev@calcite.apache.org
The Apache Calcite team is pleased to announce the release of Apache Calcite Avatica Go X.Y.Z.
Avatica is a framework for building database drivers. Avatica
defines a wire API and serialization mechanism for clients to
communicate with a server as a proxy to a database. The reference
Avatica client and server are implemented in Java and communicate
over HTTP. Avatica is a sub-project of Apache Calcite.
The Avatica Go client is a Go database/sql driver that enables Go
programs to communicate with the Avatica server.
Apache Calcite Avatica Go X.Y.Z is a minor release of Avatica Go
with fixes to the import paths after enabling support for Go modules.
This release includes updated dependencies, testing against more
targets and support for Go Modules as described in the release notes:
https://calcite.apache.org/avatica/docs/go_history.html#vX-Y-Z
The release is available here:
https://calcite.apache.org/avatica/downloads/avatica-go.html
We welcome your help and feedback. For more information on how to
report problems, and to get involved, visit the project website at
https://calcite.apache.org/avatica
Francis Chuang, on behalf of the Apache Calcite Team</code></pre></figure>
<div class="section-nav">
<div class="left align-right">
<a href="/avatica/docs/go_client_reference.html" class="prev">Previous</a>
</div>
<div class="right align-left">
<a href="/avatica/docs/history.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=""><a href="/avatica/docs/howto.html">Avatica 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="current"><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>
</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;2023
<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>
<p>
<a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy Policy</a>
</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>