avatica/docs/go_howto.html - calcite-site - Git at Google

 <!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="#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="#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="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="highlighter-rouge">v</code>. For example, tag as <code class="highlighter-rouge">v3.1.0</code> rather than <code class="highlighter-rouge">3.1.0</code>.</p>
   </li>
   <li>
     <p>Check that <code class="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="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.</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="highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-rcN</code>. The version must
 include release candidate identifiers such as <code class="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="highlighter-rouge">-rc1</code> removed, even if the
 release is a release candidate. <code class="highlighter-rouge">src</code> must also be added to the filename.</p>

 <p>For example, if we are uploading the <code class="highlighter-rouge">apache-calcite-avatica-go-3.0.0-rc1</code> folder, the files must be named
 <code class="highlighter-rouge">apache-calcite-avatica-go-3.0.0-src.tar.gz</code>. Note the inclusion of <code class="highlighter-rouge">src</code> in the filename.</p>

 <p>The tar.gz must be named <code class="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="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="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="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="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="highlighter-rouge">dist/</code> into the <code class="highlighter-rouge">calcite-dev</code> folder.</p>
   </li>
   <li>
     <p>Add the new release to the svn repository: <code class="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="highlighter-rouge">svn commit -m "apache-calcite-avatica-go-X.Y.Z-rcN" --username yourapacheusername --force-log</code>
 Note the use of <code class="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="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="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="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="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="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="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="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">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;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>
	<!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="#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="#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="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="highlighter-rouge">v</code>. For example, tag as <code class="highlighter-rouge">v3.1.0</code> rather than <code class="highlighter-rouge">3.1.0</code>.</p>
	</li>
	<li>
	<p>Check that <code class="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="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.</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="highlighter-rouge">apache-calcite-avatica-go-X.Y.Z-rcN</code>. The version must
	include release candidate identifiers such as <code class="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="highlighter-rouge">-rc1</code> removed, even if the
	release is a release candidate. <code class="highlighter-rouge">src</code> must also be added to the filename.</p>

	<p>For example, if we are uploading the <code class="highlighter-rouge">apache-calcite-avatica-go-3.0.0-rc1</code> folder, the files must be named
	<code class="highlighter-rouge">apache-calcite-avatica-go-3.0.0-src.tar.gz</code>. Note the inclusion of <code class="highlighter-rouge">src</code> in the filename.</p>

	<p>The tar.gz must be named <code class="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="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="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="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="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="highlighter-rouge">dist/</code> into the <code class="highlighter-rouge">calcite-dev</code> folder.</p>
	</li>
	<li>
	<p>Add the new release to the svn repository: <code class="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="highlighter-rouge">svn commit -m "apache-calcite-avatica-go-X.Y.Z-rcN" --username yourapacheusername --force-log</code>
	Note the use of <code class="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="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:
	<names>

	N non-binding +1s:
	<names>

	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="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="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="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="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="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="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">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 © 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 License 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>