HOWTO

Here’s some miscellaneous documentation about using Avatica.

Releasing

Preparing for release

  • You will need to have docker and Docker Compose installed.

  • If you have not set up a GPG signing key, set one up by following these instructions.

  • 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 theimport path in go.mod. The import paths in the various sample code snippets should also be updated.

  • Since we need to support Go modules, tags must be prefixed with a v. For example, tag as v3.1.0 rather than 3.1.0.

  • Check that NOTICE has the current copyright year.

Perform a dry-run

  • The script expects you to mount your ~/.gnupg directory into the /.gnupg 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~/.gnupg directory during the build.
  1. # On Linux:
  2. docker-compose run -v ~/.gnupg:/.gnupg dry-run
  4. # On Windows
  5. docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg dry-run

Build the release

  1. # On Linux:
  2. docker-compose run -v ~/.gnupg:/.gnupg release
  4. # On Windows
  5. docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg release

If the build fails, perform a clean:

  • Remove the git tag locally and remotely:
  1. git tag -d vX.Y.Z-rcA
  2. git push origin :refs/tags/vX.Y.Z-rcA
  • Clean the local repository
  1. docker-compose run clean

Check the release before uploading

The name of the release folder must be in the following format: apache-calcite-avatica-go-X.Y.Z-rcN. The version must include release candidate identifiers such as -rc0, if they are present.

The files inside the release folder must have any release candidate identifiers such as -rc1 removed, even if therelease is a release candidate. src must also be added to the filename.

For example, if we are uploading the apache-calcite-avatica-go-3.0.0-rc1 folder, the files must be named apache-calcite-avatica-go-3.0.0-src.tar.gz. Note the inclusion of src in the filename.

The tar.gz must be named apache-calcite-avatica-go-X.Y.Z-src.tar.gz.

There must be a GPG signature for the tar.gz named: apache-calcite-avatica-go-X.Y.Z-src.tar.gz.asc

There must be a SHA512 hash for the tar.gz named: apache-calcite-avatica-go-X.Y.Z-src.tar.gz.sha512

Uploading release artifacts to dev for voting

Manually

svn must be installed in order to upload release artifacts.

  • Check out the Calcite dev release subdirectory: svn co "https://dist.apache.org/repos/dist/dev/calcite/" calcite-dev.

  • Move the release folder under dist/ into the calcite-dev folder.

  • Add the new release to the svn repository: svn add apache-calcite-avatica-go-X.Y.Z-rcN. Remember to change the folder name to thecorrect release in the command.

  • Commit to upload the artifacts: svn commit -m "apache-calcite-avatica-go-X.Y.Z-rcN" —username yourapacheusername —force-logNote the use of —force-log to suppress the svn warning, because the commit message is the same as the name of the directory.

Using docker

This assumes that a release was built and the artifacts are in the dist/ folder.

  1. docker-compose run publish-release-for-voting

The script will also generate a vote email to send to the dev list. You can use this email, but make sure to check thatall the details are correct.

Send an email to the Dev list for voting:

Send out the email for voting:

  1.  
  2. To: dev@calcite.apache.org
  3. Subject: [VOTE] Release apache-calcite-avatica-go-X.Y.Z (release candidate N)
  5. Hi all,
  7. I have created a build for Apache Calcite Avatica Go X.Y.Z, release candidate N.
  9. Thanks to everyone who has contributed to this release. The release notes are available here:
  10. https://github.com/apache/calcite-avatica-go/blob/XXXX/site/_docs/go_history.md
  12. The commit to be voted upon:
  13. https://gitbox.apache.org/repos/asf?p=calcite-avatica-go.git;a=commit;h=NNNNNN
  15. The hash is XXXX.
  17. The artifacts to be voted on are located here:
  18. https://dist.apache.org/repos/dist/dev/calcite/apache-calcite-avatica-go-X.Y.Z-rcN/
  20. The hashes of the artifacts are as follows:
  21. src.tar.gz.sha512 XXXX
  23. Release artifacts are signed with the following key:
  24. https://people.apache.org/keys/committer/francischuang.asc
  26. Instructions for running the test suite is located here:
  27. https://github.com/apache/calcite-avatica-go/blob/$COMMIT/site/develop/avatica-go.md#testing
  29. Please vote on releasing this package as Apache Calcite Avatica Go X.Y.Z.
  31. To run the tests without a Go environment, install docker and docker-compose. Then, in the root of the release's directory, run:
  32. docker-compose run test
  34. When the test suite completes, run \"docker-compose down\" to remove and shutdown all the containers.
  36. The vote is open for the next 72 hours and passes if a majority of
  37. at least three +1 PMC votes are cast.
  39. [ ] +1 Release this package as Apache Calcite Go X.Y.Z
  40. [ ]  0 I don't feel strongly about it, but I'm okay with the release
  41. [ ] -1 Do not release this package because...
  44. Here is my vote:
  46. +1 (binding)
  48. Francis

After vote finishes, send out the result:

  1.  
  2. Subject: [RESULT] [VOTE] Release apache-calcite-avatica-go-X.Y.Z (release candidate N)
  3. To: dev@calcite.apache.org
  5. Thanks to everyone who has tested the release candidate and given
  6. their comments and votes.
  8. The tally is as follows.
  10. N binding +1s:
  11. <names>
  13. N non-binding +1s:
  14. <names>
  16. No 0s or -1s.
  18. Therefore I am delighted to announce that the proposal to release
  19. Apache Calcite Avatica Go X.Y.Z has passed.
  21. Thanks everyone. We’ll now roll the release out to the mirrors.
  23. Francis

Promoting a release after voting

Manually

svn must be installed in order to upload release artifacts.

NOTE: Only official releases that has passed a vote may be uploaded to the release directory.

  • Check out the Calcite release directory: svn co "https://dist.apache.org/repos/dist/release/calcite/&#34; calcite-release.

  • Copy the release into the calcite-release folder. Remember to check the name of the release’s folder to ensure that it is inthe correct format.

  • Add the release to the svn repository: svn add apache-calcite-avatica-go-X.Y.Z. Remember to change the folder name to thecorrect release in the command.

  • Commit to upload the artifacts: svn commit -m "Release apache-calcite-avatica-go-X.Y.Z" —username yourapacheusername.

  • Tag the final release in git and push it:

  1. git tag vX.Y.Z X.Y.Z-rcN
  2. git push origin vX.Y.Z

Using docker

This assumes that a rc release was tagged and pushed to the git repository.

  1. docker-compose run promote-release

Announce the release

After 24 hours, announce the release by sending an announcement to the dev listand announce@apache.org.

An example of the announcement could look like:

  1. Subject: [ANNOUNCE] Apache Calcite Avatica Go X.Y.Z released
  2. To: dev@calcite.apache.org
  4. The Apache Calcite team is pleased to announce the release of Apache Calcite Avatica Go X.Y.Z.
  6. Avatica is a framework for building database drivers. Avatica
  7. defines a wire API and serialization mechanism for clients to
  8. communicate with a server as a proxy to a database. The reference
  9. Avatica client and server are implemented in Java and communicate
  10. over HTTP. Avatica is a sub-project of Apache Calcite.
  12. The Avatica Go client is a Go database/sql driver that enables Go
  13. programs to communicate with the Avatica server.
  15. Apache Calcite Avatica Go X.Y.Z is a minor release of Avatica Go
  16. with fixes to the import paths after enabling support for Go modules.
  18. This release includes updated dependencies, testing against more
  19. targets and support for Go Modules as described in the release notes:
  21.     https://calcite.apache.org/avatica/docs/go_history.html#vX-Y-Z
  23. The release is available here:
  25.     https://calcite.apache.org/avatica/downloads/avatica-go.html
  27. We welcome your help and feedback. For more information on how to
  28. report problems, and to get involved, visit the project website at
  30.     https://calcite.apache.org/avatica
  32. Francis Chuang, on behalf of the Apache Calcite Team