Releasing Java components

Introduction

This document describes the process for releasing Vanadium Java components to JCenter and Maven Central. The components covered by this document are the

• core Vanadium Java libraries
• Vanadium Android libraries
• Gradle plugin

Background

JCenter and Maven Central are two large repositories of Java and other software binaries. Tools such as Maven and Gradle can fetch binaries from these repositories. Many projects use these tools to manage their builds. By providing Vanadium Java and Android libraries through these channels, the Vanadium team is making it easy for developers using these tools to get Vanadium into software projects.

Release process

For the purposes of the release process, we consider the Java and Android libraries to be one component. They should be released at the same time. The Gradle plugin can be released separately.

Prerequisites

The following one-time steps should be done before making your first release.

Bintray account

Release engineers should have a Bintray account, which will be used to push binaries to JCenter and Maven Central. To create a Bintray account:

• go to the Bintray home page
• click the “Sign in” button
• click on the “GitHub” button. If necessary, you will be prompted to sign into GitHub. You will then need to grant Bintray access to your GitHub account

The account is now created. You need to be part of the Vanadium Bintray organization. To do this:

• visit the Vanadium Bintray organization's page
• click the “Join” button
• click the “Send” button to send a message to the organization's owners

A member of the Vanadium organization will approve the request.

Once your request has been approved, you need to add your API key to the Gradle configuration.

• visit https://bintray.com/profile/edit (signing in if necessary)
• generate an API key, copy it to $HOME/.gradle/gradle.properties. The file should look like

bintrayUsername=yourGithubUsername
bintrayApiKey=yourApiKey

Maven Central account

You need to create a Sonatype JIRA account. To do this:

• visit the JIRA account creation page and create an account
• send an email to the vanadium-discuss mailing list. Your email should be something like:

To: vanadium-discuss@v.io
Subject: Add Maven Central releaser

Hi there,

I'd like to be added to list of Maven Central releasers. My JIRA username is

<your JIRA username>

Thanks,
New releaser

Gradle plugin

The steps to release the Gradle plugin are:

• determine the release number to use. To determine the current release number, go to the JCenter Gradle plugin page. If this is a major release, increment the major release number and set the minor number to zero. If it's a minor release, increment the minor number and leave the major number unchanged
• edit $JIRI_ROOT/release/java/gradle-plugin/build.gradle and change the releaseVersion variable to the new release number
• run the following commands:

cd $JIRI_ROOT/release/java/gradle-plugin
./gradlew clean bintrayUpload

This command will build and upload the VDL plugin to Bintray.

• go to the Gradle plugin Bintray page and make sure you're signed in
• click on the version number of the version you just uploaded
• you should see a notice such as “You have 4 unpublished item(s) for this version”, click on the associated “Publish” button

The new version is now published to JCenter. For Maven Central, follow these additional steps:

• click on the “Maven Central” link
• enter your JIRA username and password that you created in the Maven Central account prerequisite step
• ensure the “Close and release repository when done” check box is checked
• click the “Sync” button

Assuming there were no errors, the new version will be pushed out to Maven Central shortly (usually within a matter of 10 minutes or so). You can verify by visiting the Maven Central page for the plugin. When the new version number appears in the list, the plugin has been published.

Java and Android libraries

Releasing these libraries is similar to releasing the Gradle plugin with one notable exception: it must be performed once on Linux and once on Darwin. This is due to the fact that, at this point in time, the Vanadium Java libraries cannot be cross-compiled between the two platforms.

Building

On either Linux or Darwin, perform the following steps:

• determine the release number to use. To determine the current release number, go to the JCenter Vanadium library page. If this is a major release, increment the major release number and set the minor number to zero. If it's a minor release, increment the minor number and leave the major number unchanged
• edit $JIRI_ROOT/release/java/lib/build.gradle and change the releaseVersion variable to the new release number
• edit $JIRI_ROOT/release/java/android-lib/build.gradle and change the releaseVersion variable to the same release number
• run the following commands:

cd $JIRI_ROOT/release/java
./gradlew :lib:clean :lib:bintrayUpload
./gradlew :android-lib:clean :android-lib:bintrayUpload

Now, switch to the other platform (i.e. not the one you used for the above steps) and:

• edit the $JIRI_ROOT/release/java/lib/build.gradle file
• change the releaseVersion variable to match the same variable from the previous steps
• find the line that reads

    publications = ['mavenJava', 'mavenNoNatives', 'mavenNatives']

• we've already published mavenJava and mavenNoNatives, remove those entries. Do not check in your changes. The line should now read

    publications = ['mavenNatives']

• run the following commands:

cd $JIRI_ROOT/release/java
./gradlew :lib:clean :lib:bintrayUpload

Publishing

The binaries for the Vanadium and Vanadium Android libraries are now uploaded to Bintray. Time to publish them to JCenter and Maven Central.

• go to the Vanadium library Bintray page and make sure you're signed in
• click on the version number of the version you just uploaded
• you should see a notice such as “You have 8 unpublished item(s) for this version”, click on the associated “Publish” button

The new Vanadium library version is now published to JCenter. For Maven Central, follow these additional steps:

• click on the “Maven Central” link
• enter your JIRA username and password that you created in the Maven Central account prerequisite step
• ensure the “Close and release repository when done” check box is checked
• click the “Sync” button

The Vanadium library will now be pushed out to Maven Central in a few minutes. Now go to the Vanadium Android library Bintray page and repeat the publishing steps.

Building and Running a local version of the libraries

To use a local version of the android and java libraries you need to publish the libraries to the maven local repository.

• run the following commands:

cd $JIRI_ROOT/release/java
./gradlew :lib:clean :lib:publishToMavenLocal
./gradlew :android-lib:clean :android-lib:publishToMavenLocal

• you may now use your local libraries by specifying mavenLocal() in the “alprojects” repositories clause of your project build.gradle file.
• For Android Studio to pick up these changes you will need to run “Build >> Clean project” in your IDE.

Syncbase Library

To release a new version of the high-level syncbase API, follow the above steps, except to upload to bintray, run:

cd $JIRI_ROOT/release/java/syncbase
./gradlew clean bintrayUpload

And to use a local version of the library, run:

cd $JIRI_ROOT/release/java/syncbase
./gradlew clean install

Syncbase Tutorials

When releasing a new version of the Syncbase library, be sure to also update the Syncbase tutorials in the website repo.

Refer to the upgrade-syncbase-android build rule in the website Makefile's for instructions.