Here's some miscellaneous documentation about using Avatica.
Prerequisites are Java (JDK 8 or later) and Gradle (version 6.8.1) on your path.
(The source distribution does not include the Gradle wrapper; therefore you need to install Gradle manually.)
Unpack the source distribution .tar.gz
file, cd
to the root directory of the unpacked source, then build using Gradle:
{% highlight bash %} $ tar xvfz apache-calcite-avatica-1.18.0-src.tar.gz $ cd apache-calcite-avatica-1.18.0-src $ gradle build {% endhighlight %}
Running tests describes how to run more or fewer tests (but you should use the gradle
command rather than ./gradlew
).
Prerequisites are Git, and Java (JDK 8 or later) on your path.
Create a local copy of the GitHub repository, cd
to its root directory, then build using Gradle:
{% highlight bash %} $ git clone git://github.com/apache/calcite-avatica.git avatica $ cd avatica $ ./gradlew build {% endhighlight %}
Running tests describes how to run more or fewer tests.
The test suite will run by default when you build, unless you specify -x test
{% highlight bash %} $ ./gradlew assemble # build the artifacts $ ./gradlew build -x test # build the artifacts, verify code style, skip tests $ ./gradlew check # verify code style, execute tests $ ./gradlew test # execute tests $ ./gradlew checkstyleMain checkstyleTest # verify code style {% endhighlight %}
You can use ./gradlew assemble
to build the artifacts and skip all tests and verifications.
Prerequisites are Docker and Docker Compose.
{% highlight bash %} docker-compose run test {% endhighlight %}
See the [developers guide]({{ site.baseurl }}/develop/#contributing).
See the [developers guide]({{ site.baseurl }}/develop/#getting-started).
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.
The following sections are of interest to Calcite committers and in particular release managers.
Follow instructions here to create a key pair. (On Mac OS X, I did brew install gpg
and gpg --gen-key
.)
Add your public key to the KEYS
file by following instructions in the KEYS
file. (The KEYS
file is not present in the git repo or in a release tar ball because that would be redundant.)
By default, Gradle 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 gpg-agent
.
This can be started automatically via an ~/.xsession
on Linux or some scripting in your shell's configuration script of choice (e.g. ~/.bashrc
or ~/.zshrc
)
{% highlight bash %} GPG_AGENT=$(which gpg-agent) GPG_TTY=tty
export GPG_TTY if [[ -f “$GPG_AGENT” ]]; then envfile=“${HOME}/.gnupg/gpg-agent.env”
if test -f “$envfile” && kill -0 $(grep GPG_AGENT_INFO “$envfile” | cut -d: -f 2) 2>/dev/null; then source “$envfile” else eval “$(gpg-agent --daemon --log-file=~/.gpg/gpg.log --write-env-file “$envfile”)” fi export GPG_AGENT_INFO # the env file does not contain the export statement fi {% endhighlight %}
Also, ensure that default-cache-ttl 6000
is set in ~/.gnupg/gpg-agent.conf
to guarantee that your credentials will be cached for the duration of the build.
Gradle provides multiple ways to configure project properties. For instance, you could update $HOME/.gradle/gradle.properties
.
Note: the build script would print the missing properties, so you can try running it and let it complain on the missing ones.
The following options are used:
{% highlight properties %} asfCommitterId= asfNexusUsername= asfNexusPassword= asfSvnUsername= asfSvnPassword= {% endhighlight %}
When asflike-release-environment is used, the credentials are taken from asfTest...
(e.g. asfTestNexusUsername=test
)
Note: if you want to uses gpg-agent
, you need to pass useGpgCmd
property, and specify the key id via signing.gnupg.keyName
.
Before you start:
{% highlight bash %}
git clean -xn
./gradlew -Pasf publish {% endhighlight %}
Before you start:
README
, site/_docs/howto.md
, site/_docs/docker_images.md
have the correct version number.site/_docs/howto.md
has the correct Gradle version.NOTICE
has the current copyright year.calcite.avatica.version
has the proper value in /gradle.properties
.site/_docs/history.md
. Include the commit history, and say which versions of Java, Guava and operating systems the release is tested against../gradlew dependencyCheckUpdate dependencyCheckAggregate
.The release candidate process does not add commits, so there's no harm if it fails. It might leave -rc
tag behind which can be removed if required.
You can perform a dry-run release with a help of https://github.com/vlsi/asflike-release-environment That would perform the same steps, however it would push changes to the mock Nexus, Git, and SVN servers.
If any of the steps fail, fix the problem, and start again from the top.
Pick a release candidate index and ensure it does not interfere with previous candidates for the version.
{% highlight bash %}
git clean -xn
./gradlew prepareVote -Prc=1
./gradlew prepareVote -Prc=1 -Pasf {% endhighlight %}
You will need to have Docker and Docker Compose installed.
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.
Start the asflike-release-environment to prepare a staging environment for a dry-run.
{% highlight bash %}
docker-compose run -v ~/.gnupg:/.gnupg dry-run
docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg dry-run
docker-compose run -v ~/.gnupg:/.gnupg publish-release-for-voting
docker-compose run -v /c/Users/username/AppData/Roaming/gnupg:/.gnupg publish-release-for-voting {% endhighlight %}
release/build/distributions
directory should be these 3 files, among others:apache-calcite-avatica-
..tar.gz
(currently there is no binary distro), check that all files belong to a directory called apache-calcite-avatica-X.Y.Z-src
.NOTICE
, LICENSE
, README
, README.md
README
is correctKEYS
, gradlew
, gradlew.bat
, gradle-wrapper.jar
, gradle-wrapper.properties
core/build/libs/avatica-core-X.Y.Z.jar
and server/build/libs/avatica-server-X.Y.Z-sources.jar
), verify that the META-INF
directory contains the correct contents for LICENSE
and NOTICE
per the source/classes contained. Refer to the ASF licensing documentation on what is required.Verify the staged artifacts in the Nexus repository:
Build Promotion
, click Staging Repositories
Staging Repositories
tab there should be a line with profile org.apache.calcite
If something is not correct, you can fix it, commit it, and prepare the next candidate. The release candidate tags might be kept for a while.
{% highlight bash %}
gpg --recv-keys key
curl -O https://dist.apache.org/repos/dist/release/calcite/KEYS
function checkHash() { cd “$1” for i in *.{pom,gz}; do if [ ! -f $i ]; then continue fi if [ -f $i.sha512 ]; then if [ “$(cat $i.sha512)” = “$(shasum -a 512 $i)” ]; then echo $i.sha512 present and correct else echo $i.sha512 does not match fi else shasum -a 512 $i > $i.sha512 echo $i.sha512 created fi done } checkHash apache-calcite-avatica-X.Y.Z-rcN {% endhighlight %}
Release vote on dev list. Note: the draft mail is printed as the final step of prepareVote
task, and you can find the draft in /build/prepareVote/mail.txt
{% highlight 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. 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.sha512 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 Avatica 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 {% endhighlight %}
After vote finishes, send out the result:
{% highlight 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:
N non-binding +1s:
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 {% endhighlight %}
Use the Apache URL shortener to generate shortened URLs for the vote proposal and result emails. Examples: s.apache.org/calcite-1.2-vote and s.apache.org/calcite-1.2-result.
After a successful release vote, we need to push the release out to mirrors, and other tasks.
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.
In JIRA, search for all issues resolved in this release, 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”.
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.
{% highlight bash %}
./gradlew publishDist -Prc=1
./gradlew publishDist -Prc=1 -Pasf {% endhighlight %}
If there are more than 2 releases in SVN (see https://dist.apache.org/repos/dist/release/calcite), clear out the oldest ones:
{% highlight bash %} svn rm https://dist.apache.org/repos/dist/release/calcite/apache-calcite-avatica-X.Y.Z {% endhighlight %}
The old releases will remain available in the release archive.
This assumes that a rc release was tagged and pushed to the git repository.
{% highlight bash %} docker-compose run promote-release {% endhighlight %}
Add a release note by copying [site/_posts/2016-11-01-release-1.9.0.md]({{ site.sourceRoot }}/site/_posts/2016-11-01-release-1.9.0.md), generate the javadoc and copy to site/target/avatica/javadocAggregate
publish the site, and check that it appears in the contents in news.
After 24 hours, announce the release by sending an email to announce@apache.org. You can use the 1.8.0 announcement as a template. Be sure to include a brief description of the project.
{: #publish-the-web-site}
See instructions in [site/README.md]({{ site.sourceRoot }}/site/README.md).